表格是 GFM 扩展
表格语法是 GitHub Flavored Markdown（GFM）的扩展，不属于 CommonMark 标准。在 GitHub、GitLab、VS Code、Obsidian 等支持 GFM 的环境中可以渲染，但在纯 CommonMark 解析器中会显示为原始文字。
基本表格语法
Markdown 表格由三个部分组成：表头行、分隔行（---）和数据行，各列用 | 分隔。
源码
| 语言 | 出现年份 | 主要用途 | | ---------- | -------- | ------------- | | Python | 1991 | AI / 数据科学 | | JavaScript | 1995 | Web 前端 | | Go | 2009 | 后端服务 | | Rust | 2015 | 系统编程 |
渲染效果
| 语言 | 出现年份 | 主要用途 |
|---|---|---|
| Python | 1991 | AI / 数据科学 |
| JavaScript | 1995 | Web 前端 |
| Go | 2009 | 后端服务 |
| Rust | 2015 | 系统编程 |
表格语法的解析规则
了解 GFM 表格的解析规则，有助于处理边界情况：
表头行（Header Row）
第一行是表头，每列的内容成为
<th>（表格标题）元素。表头内容通常加粗显示（由 CSS 控制）。分隔行（Delimiter Row）
第二行必须只包含
- 字符和可选的冒号（:）。这一行触发表格的解析，也控制列的对齐方式。每个单元格至少需要一个 -。数据行（Data Rows）
第三行开始是数据行，每行对应一个
<tr>。列数可以少于表头列数（缺少的列视为空单元格），但不能多于表头列数。外侧竖线（Surrounding Pipes）
首尾的
| 是可选的，但实践中建议保留，使表格对齐更清晰。没有首尾 | 的写法：语言 | 年份（也有效）。最小合法表格
# 最简写法（首尾没有 | ，分隔行只有一个 -） A | B - | - 1 | 2 # 也是合法的（空表，只有表头） | 名称 | 状态 | | --- | --- |
列对齐（Column Alignment）
在分隔行的 - 两端加冒号控制该列的对齐方式：
源码
| 左对齐 | 居中对齐 | 右对齐 | | :------ | :--------: | ------: | | 苹果 | 香蕉 | 橙子 | | 1234 | 5678 | 9012 | | 长文字 | 更长的文字 | 短 |
渲染效果
| 左对齐 | 居中对齐 | 右对齐 |
|---|---|---|
| 苹果 | 香蕉 | 橙子 |
| 1234 | 5678 | 9012 |
| 长文字 | 更长的文字 | 短 |
| 分隔行写法 | 对齐方式 | HTML 输出 |
|---|---|---|
:--- 或 :-- | 左对齐 | style="text-align:left" |
:---: 或 :--: | 居中对齐 | style="text-align:center" |
---: 或 --: | 右对齐 | style="text-align:right" |
---（无冒号） | 默认（通常左对齐） | 无 style 属性 |
对齐的实践建议
- 文字列：左对齐（默认即可）
- 数字、金额、百分比：右对齐（数字对齐方便比较大小）
- 状态标志（✅ ❌）、图标、序号：居中对齐
- 表头说明（列名）：跟随列内容对齐
表格中使用格式化
表格单元格内可以使用大多数内联 Markdown 语法：
源码
| API 端点 | 状态 | 说明 |
| --------------------- | :---------------: | ----------------------- |
| `GET /api/users` | ✅ 已完成 | 返回用户列表 |
| `POST /api/users` | 🚧 进行中 | **需要验证邮箱** |
| `DELETE /api/users` | ❌ 未开始 | 需要管理员权限 |
| `GET /api/users/{id}` | ✅ 已完成 | 返回单个用户，[文档][1] |
[1]: https://example.com/api-docs
渲染效果
| API 端点 | 状态 | 说明 |
|---|---|---|
GET /api/users | ✅ 已完成 | 返回用户列表 |
POST /api/users | 🚧 进行中 | 需要验证邮箱 |
DELETE /api/users | ❌ 未开始 | 需要管理员权限 |
GET /api/users/{id} | ✅ 已完成 | 返回单个用户，文档 |
表格单元格内可用的格式
| 格式 | 是否支持 | 备注 |
|---|---|---|
加粗 **text** | ✅ 支持 | |
斜体 *text* | ✅ 支持 | |
删除线 ~~text~~ | ✅ 支持 | GFM 环境 |
内联代码 `code` | ✅ 支持 | |
链接 [text](url) | ✅ 支持 | |
图片  | ✅ 支持 | 建议用小图 |
| Emoji ✅ ❌ 🚀 | ✅ 支持 | |
| 换行 | ❌ 不支持 | 单元格内无法换行，只能用 HTML |
| 多段落 | ❌ 不支持 | 单元格内无法有多段落 |
| 列表 | ❌ 不支持 | 单元格内无法嵌套列表 |
| 代码块 | ❌ 不支持 | 单元格内无法使用围栏代码块 |
单元格内换行的解决方法
当必须在单元格内换行时，使用 HTML <br>：
| 功能 | 说明 | | -------- | --------------------------------------- | | 多行内容 | 第一行<br>第二行<br>第三行 | | 列表替代 | ① 选项 A<br>② 选项 B<br>③ 选项 C |
| 功能 | 说明 |
|---|---|
| 多行内容 | 第一行 第二行 第三行 |
| 列表替代 | ① 选项 A ② 选项 B ③ 选项 C |
表格中的特殊字符处理
竖线（|）的转义
单元格内容中包含 | 时，需要用反斜杠转义：
| 表达式 | 含义 | | ------------ | ----------------- | | `a \| b` | 逻辑或（OR） | | `a && b` | 逻辑与（AND） | | `a ? b : c` | 三元运算符 |
也可以把 | 包在内联代码中（代码块内的 | 不需要转义）：
| 命令 | 说明 | | ----------------------- | ----------------- | | `cat file.txt | grep x` | 管道命令 |
其他需要转义的字符
- 单元格开头的
-可能被解析为列表，但通常没问题（因为表格内不会解析列表） - 单元格内的反引号正常使用，不影响表格
- HTML 实体（如
<）在表格内工作正常
表格格式化与工具辅助
手动对齐大型表格非常繁琐，以下工具可以帮助：
VS Code：Markdown All in One 插件
# 安装插件后 Alt+Shift+F → 格式化整个 Markdown 文件（含表格对齐） # 也可以在命令面板中 Ctrl+Shift+P → "Format Document"
Prettier 自动格式化
# 安装 prettier npm install -D prettier # 格式化 Markdown 文件 npx prettier --write README.md # .prettierrc 配置 { "proseWrap": "always", "printWidth": 100 }
在线表格生成工具
| 工具 | 特点 |
|---|---|
| Tables Generator（tablesgenerator.com） | 可视化生成/导入 CSV，支持导出多种格式 |
| Markdown Tables（快捷键 Alt+Shift+F） | VS Code 插件，就地格式化 |
| markdown-table（npm 包） | 编程式生成，适合从数据自动生成表格 |
不对齐 vs 对齐的效果
不对齐（仍然有效）
| 名称 | 年龄 | 城市 | |---|---|---| | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |
对齐（更易维护）
| 名称 | 年龄 | 城市 | | ---- | ---- | ---- | | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |
虽然不对齐的表格在渲染后效果完全相同，但对齐的表格在纯文本编辑器中可读性更好（这是 Markdown 可读性优先原则的体现）。
复杂表格：超出 GFM 能力的场景
GFM 表格语法不支持以下特性，需要使用 HTML <table>：
合并单元格（colspan / rowspan）
<table>
<thead>
<tr>
<th colspan="3">前端技术（跨3列）</th>
</tr>
<tr>
<th>框架</th>
<th>语言</th>
<th>用途</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="2">JavaScript</td> <!-- 跨2行 -->
<td>React</td>
<td>SPA 应用</td>
</tr>
<tr>
<td>Vue</td>
<td>渐进式开发</td>
</tr>
</tbody>
</table>
| 前端技术（跨3列标题） | ||
|---|---|---|
| 框架 | 语言 | 用途 |
| JavaScript | React | SPA 应用 |
| Vue | 渐进式开发 | |
多级表头
GFM 表格只支持单级表头，多级表头需要 HTML：
<table>
<thead>
<tr>
<th rowspan="2">产品</th>
<th colspan="2">2025 Q4</th>
<th colspan="2">2026 Q1</th>
</tr>
<tr>
<th>销量</th><th>增长</th>
<th>销量</th><th>增长</th>
</tr>
</thead>
<tbody>
<tr><td>产品A</td><td>1200</td><td>+15%</td><td>1380</td><td>+12%</td></tr>
</tbody>
</table>
TIP（何时用 HTML 表格）当你需要以下特性时，直接写 HTML 表格：① 合并单元格（colspan/rowspan）；② 多级表头；③ 单元格内有多行内容；④ 需要
<caption> 表格标题；⑤ 需要 <tfoot> 汇总行。GFM 表格适合简单的数据展示，HTML 表格适合复杂的报表。
表格的使用场景和最佳实践
适合用表格的场景
- 对比多个选项（框架比较、工具比较）
- API 端点列表（方法、路径、说明）
- 命令行参数说明（参数名、类型、默认值、说明）
- 版本变更记录（版本、日期、变更内容）
- 配置项说明（键名、类型、默认值、描述）
不适合用表格的场景
- 只有两列的简单键值对（用定义列表或
**键**：值格式更简洁） - 内容太长，每行超过屏幕宽度（用列表更适合）
- 只有一行数据（用列表）
- 需要合并单元格（直接用 HTML 表格）
表格内容的格式规范
# ✅ 好的表格实践 | 参数名 | 类型 | 默认值 | 说明 | | ------- | -------- | :----: | -------------------------- | | host | `string` | `localhost` | 服务器主机名 | | port | `number` | `3000` | 监听端口号 | | debug | `boolean`| `false`| 是否开启调试日志 | # 要点： # - 内联代码标注类型（使代码类型更清晰） # - 默认值也用代码格式标注 # - 说明列用自然语言，简洁明了 # - 类型列和默认值列居中对齐
小结
本章要点
- 表格是 GFM 扩展，CommonMark 不支持；GitHub/VS Code/Obsidian 等支持
- 基本语法：表头行 | 分隔行（
---）| 数据行，列用|分隔 - 列对齐：
:---左对齐，:---:居中，---:右对齐；数字列建议右对齐 - 单元格内支持加粗、斜体、代码、链接、Emoji；不支持换行、多段落、嵌套列表
- 单元格内
|需要转义为\|（或放在代码块内） - 复杂表格（合并单元格、多级表头）需要使用 HTML
<table> - 使用 VS Code Markdown All in One 或 Prettier 自动格式化对齐表格