Markdown 表格语法：用法、格式与对齐技巧

结论先行

Markdown 表格仅通过管道符 | 和连字符 - 即可构建。

| 姓名 | 邮箱 | 权限 |
| --- | --- | --- |
| 张三 | zhangsan@example.com | admin |
| 李四 | lisi@example.com | viewer |

如果手动编写繁琐，你可以将 CSV 粘贴到 CSV to Markdown 转换器 中，立即生成格式化的表格。以下将详细解析表格语法。

基本语法 — 管道符与连字符

Markdown 表格由三个部分组成：

1. 表头行 — 列名通过管道符 | 分隔
2. 分隔行 — 连字符 - 分隔表头与数据（惯例上使用 3 个）
3. 数据行 — 每个单元格通过管道符分隔

| 项目 | 值 |
| --- | --- |
| CPU | Apple M4 |
| 内存 | 16 GB |

行首和行末的管道符可以省略，但为了可读性通常建议保留。无需在源文件中对齐列宽，渲染时会自动调整。

管道符与分隔行的结构

管道符 | 用于分隔列。分隔行（也称为表头分隔行或虚线行）由连字符 - 组成，向渲染器指示表头与数据的边界。

关于管道符和连字符，需了解以下规则：

• 每列使用 3 个连字符（---）是惯例，而非解析器规则。GFM 规范未规定最小数量，-- 或单个 - 在 GFM 渲染器中也能正常显示表格（已在 marked 18.0.5 / remark-gfm 4.0.1 中验证）。保持 3 个是为了可读性
• 真正破坏表格的是表头行与分隔行的列数不一致。根据 GFM 规范，如果列数不匹配，表格将不会被识别
• 行首和行末的管道符可以省略，但建议保留以提升可读性。| A | B | 和 A | B 的渲染效果相同
• 对齐冒号（:---, :---:, ---:）只能放在分隔行中，不能出现在数据行
• 在 GFM 中，表头行是必需的。CommonMark 核心规范中没有表格定义，因此无表头的表格仅存在于自定义扩展中

如果表格未渲染，首先检查表头行与分隔行的列数。如果不一致，表格将完全不被识别。其次常见的原因是表格前缺少空行，而连字符数量极少是问题所在。

对齐设置 — 左对齐、居中、右对齐

在分隔行中添加冒号 : 可以控制列的对齐方式：

| 商品 | 数量 | 单价 |
| :--- | :---: | ---: |
| 苹果 | 3 | 12.00 |
| 橙子 | 10 | 8.00 |

将数值列设为右对齐，可以使数字位数对齐，便于阅读。

GFM (GitHub Flavored Markdown) 支持

GitHub、GitLab、Notion、Obsidian 等主要平台均支持 GFM 表格语法。上述介绍的语法可直接使用。

以下是 GFM 表格中值得记住的要点：

• 表头行是必需的。GFM 中无法创建无表头的表格
• 分隔行使用连字符（---），惯例为每列 3 个，但规范允许更少
• 单元格内支持内联格式（代码、链接、删除线等）
• 如果表格前后没有空行，解析器可能无法识别为表格

各平台管道符表格支持情况

表格的三个基本要素，即管道符 | 表格、分隔行中的冒号对齐（:---）和单元格内换行用的 <br>，在不同平台上的支持情况有所不同。

关于表格的补充说明：

• GitHub 遵循 GitHub Flavored Markdown 规范的 Tables (extension) 部分在新标签页中打开，定义了管道符表格和分隔行中的冒号对齐。单元格被解析为内联内容，因此允许 <br> 这样的内联 HTML，GitHub 将其渲染为单元格内换行。
• GitLab Flavored Markdown 也文档化了相同的管道符表格和对齐语法，其官方文档明确指出可以使用 <br> 标签在单元格内强制多行。
• Obsidian 支持管道符表格和冒号对齐，并且实际上将 <br> 标签渲染为单元格内换行。
• Notion 可以导入或粘贴管道符表格，但会将其转换为自身的表格块，而非渲染 GFM。Notion 表格没有每列对齐选项，因此对齐冒号（:---）没有视觉效果，单元格内的 <br> 也不会渲染为换行。

具体规则定义在 GitHub Flavored Markdown 规范的 Tables (extension) 部分在新标签页中打开 中。纯 CommonMark在新标签页中打开 中没有表格语法定义，因此表格在技术上是 GFM 的扩展功能。严格实现 CommonMark 且未采用扩展的渲染器不会将表格显示为表格。CommonMark 与 GFM 的完整差异见 CommonMark 与 GFM 的区别，GFM 表格的对齐、转义与换行写法汇总见 GFM 表格语法速查表。

分隔行的实际行为 — 4 种渲染器验证 (GitHub / marked / remark-gfm / CommonMark)

GFM Tables 扩展将分隔行定义为“内容仅为连字符（-），且可选地在首尾放置冒号（:）的单元格”，并未规定连字符的最小数量。GitHub 自身文档说明“每列至少 3 个连字符”，但规范中并无此规则，GitHub 渲染器接受 1 个连字符。规范自身的对齐示例甚至使用了 1 个连字符的 :-:。

为确定这一主张，我们将同一组边缘用例通过了 GitHub 生产渲染器（通过 Markdown API）、marked、remark-gfm 和无扩展的严格 CommonMark 管道线。复现脚本位于仓库的 scripts/benchmarks/markdown-table-parsers/。2026-07-15 实测，marked 18.0.5 / remark-gfm 4.0.1 / remark-parse 11.0.0：

有三个值得注意的发现：

• 连字符数量不影响表格是否渲染。在 GitHub / marked / remark-gfm 中，1 个连字符与 3 个的行为完全相同，“3 个”是用于可读性的惯例，而非要求
• 唯一的实质性解析器差异在于倒数第二行。省略外部管道符并使用 1 个连字符时，分隔行以 - 开头，GitHub 和 remark-gfm 将其读取为列表标记，而 marked 仍将其处理为表格。如果省略外部管道符，请保留至少 2 个连字符
• 在任何渲染器中，导致表格确定损坏的是分隔行列数与表头不一致。表格不被识别，回退为段落，且不产生错误消息

管道符与特殊字符转义

如果在单元格内直接书写管道符 |，会被误认为列分隔符从而导致表格损坏。安全书写的方法有两种：

| 命令 | 含义 |
| --- | --- |
| cmd1 \| cmd2 | 使用反斜杠转义 |
| cmd1 | cmd2 | 使用 HTML 实体表示 |

• \|（反斜杠转义）在 GitHub、GitLab、Notion、Obsidian 等主要 GFM 渲染器中有效
• |（HTML 数字字符引用）是当渲染器无法正确处理 \| 时的安全后备方案，且在编辑器间复制粘贴时不易损坏

如果在单元格内显示反斜杠本身，请书写 \\。如果需要插入不换行空格，请使用  。转义字符的完整列表及各渲染器的支持情况见 Markdown 转义字符一览。

即用反引号包裹也无法保护管道符。尽管有些资料解释代码片段内的管道符无需转义，但表格的单元格分割发生在内联元素解析之前，因此即使在使用反引号时也需要反斜杠转义。

| a | b |
| --- | --- |
| `x | y` | z |

将此行通过 GitHub Markdown API、marked 18.0.5 和 remark-gfm 4.0.1 时，三种渲染器都会拆分代码片段单元格。输出的 <td> 仅有 2 个，内容分别为 `x 和 y`，反引号保持未配对状态，第 3 个值 z 丢失（2026-08-29 实测，复现步骤见 scripts/benchmarks/markdown-table-parsers/）。反斜杠转义在代码片段内同样有效——同一基准测试中 `a \| b` 的案例在三种渲染器中均保持完整，因此这里的解决方法也是 \|。

简体字在等宽字体下的对齐问题

这是一个针对简体中文读者的特有痛点。简体中文字符在大多数等宽字体（Monospaced Font）中占据 2 个字符的宽度，而英文字母和数字通常占据 1 个。

这导致在源代码编辑器中，如果表格内容混合了中文和英文，视觉上的列对齐会显得参差不齐。

例如：

| 姓名 | Name  |
| ---  | ---   |
| 张三 | John  |
| 李四 | Alice |

在等宽字体下，姓名 的宽度大约是 Name 的两倍，导致后续列无法在视觉上对齐。

建议：

• 不要试图通过手动添加空格来对齐源代码中的列，因为这通常会因为中文字符宽度问题而失败。
• 依赖渲染引擎的自动调整。
• 如果必须在纯文本环境中保持对齐（例如日志文件），请意识到中英文宽度差异，或避免混合使用导致视觉错位。
• 在渲染后的网页中，这通常不是问题，因为浏览器会根据内容自动调整列宽。

常见陷阱

如果管道符直接显示或表格中途损坏，原因通常是以下之一。按症状逐一排查修复的方法见 Markdown 表格不显示或错乱？按症状逐一排查修复。

单元格内换行

Markdown 表格规范不支持单元格内换行。如果必须换行，可以直接写入 HTML 标签 <br>，但并非所有平台都支持。

空单元格

如果想让单元格为空，只需在管道符之间留空格。连续使用管道符也可以，但插入空格更易读。

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

列数不一致

如果表头有 3 列，但数据行只有 2 列，大多数解析器会将缺失部分处理为空单元格。反之，如果数据行列数过多，多余部分将被截断。保持列数一致是安全的做法。

大量数据 — 从 CSV 自动生成

手动编写 5 行左右的表格没问题，但超过 20 行或列数较多时，手动工作既耗时又易错。将 Excel 或电子表格的数据复制为 CSV，然后粘贴到 CSV to Markdown 转换器 中，工具会自动处理管道符对齐和转义。CSV 转 Markdown 表格的详细步骤与常见问题见 CSV 转 Markdown 表格的完整指南。

常见问题

Markdown 表格可以没有表头吗？

在 GFM 中，表头行是必需的。即使不需要显示表头，也需要书写空的表头行和分隔行。

单元格内可以放链接或图片吗？

可以。内联 Markdown（如 [文本](URL) 或 ![alt](图片URL)）可以在单元格内使用。但表格横向过宽会降低可读性，因此限制在链接范围内是现实的。

可以指定表格列宽吗？

Markdown 规范中没有列宽指定方法。渲染时会根据内容自动调整。如果需要精细控制，需使用 HTML 的 <table>。

总结

Markdown 表格语法简单，记住管道符和连字符即可轻松创建表格。虽然存在对齐设置或转义等详细规则，但掌握基础就足够应对大多数场景。

处理行数较多的数据时，推荐你将 CSV 粘贴到 CSV to Markdown 转换器，即可生成精确的 Markdown 表格，省去手动编写的麻烦。