GitHub Markdown 表格语法速查表：对齐、空单元格、换行与管道符转义

TL;DR — GFM 表格语法速查表

GFM 表格是 GitHub Flavored Markdown 规范中定义的管道符分隔表格，是纯 CommonMark 核心规范不包含的扩展功能。

• 表格由表头行、分隔行（---，每列习惯用 3 个）和数据行组成，用管道符 | 分隔。表格前后必须有空行。
• 对齐方式通过分隔行的冒号位置指定：:--- 左对齐 / :---: 居中对齐 / ---: 右对齐。
• 单元格内的管道符用反斜杠转义（\|），在不支持的环境中使用 HTML 实体 | 作为后备。
• 单元格内换行直接写 <br> 标签。在 GitHub 和 GitLab 上正常工作，但 Obsidian 或 Notion 等可能因编辑模式或导入路径不同而表现不同。
• 单元格合并、多段落、代码块等块级元素在 GFM 表格中不可用。如果需要，请切换到 HTML <table>。
• 不想手动输入管道符？只需将 CSV 数据粘贴到 CSV to Markdown，即可立即生成 GFM 兼容的表格。

这篇文章是一张速查表，供已经大致了解如何编写 Markdown 表格的人快速查阅语法。如果你想从零开始逐步学习创建表格，请先阅读基础教程。

GFM 表格能做什么・不能做什么

如果需要块级元素或合并单元格，请直接编写 HTML <table> 而不是 Markdown（参见下文“Markdown 表格无法实现的事情”）。

基本结构 — 通过最小对确认

GFM 表格由表头行、分隔行和数据行三部分组成。分隔行的连字符每列习惯用 3 个（GFM 规范没有规定最少数量），行首和行末的管道符可以省略。

语法：

| 姓名 | 权限 |
| --- | --- |
| 张伟 | admin |
| 李娜 | viewer |

结果：

最小的表格（1 行表头 + 1 行数据）如下：

| key | value |
| --- | --- |
| name | FormatArc |

对齐语法速查表

通过分隔行中冒号（:）的位置来指定列的对齐方式。

语法：

| 商品 | 数量 | 单价 |
| :--- | :---: | ---: |
| 苹果 | 3 | 120 |
| 橘子 | 10 | 80 |

结果：

将数值列右对齐可以使数字对齐，提高可读性。

单元格内可用的格式

单元格内部可以使用行内元素。不能使用代码块、列表或多段落。

可以在单元格内放置图片，但表格会变得很高且难以阅读，因此实际使用中建议限制在小型图标级别。

空单元格（空白单元格）的写法

将单元格留空是有效的语法。如果管道符之间不写任何内容，该单元格将渲染为空白。

语法：

| 姓名 | 权限 | 备注 |
| --- | --- | --- |
| 张伟 | admin | |
| 李娜 | | viewer |

结果：

处理空单元格时需注意两点：

• 必须保持列数与表头一致。空单元格是 | |（两个管道符之间为空），而不是省略管道符。如果少了一个管道符，列数就会少一列，导致表格错乱。
• 如果一行的第一个单元格为空，且省略了行首的管道符，某些渲染器可能会误认为第一列缺失。保留行首的 |（| | 值 |），或者作为后备方案在第一个单元格放置空链接 []()，可以防止列丢失。

空单元格不是合并单元格。GFM 没有 rowspan 或 colspan，因此空白单元格只是空白，不会在视觉上与上方或旁边的单元格合并。如果需要合并，请切换到 HTML <table>（下文将述）。

管道符・特殊字符转义速查表

如果在单元格中直接写入 |，会被误认为列分隔符，导致表格结构崩溃。安全的写法有两种：

语法：

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

结果：

此外，如果想显示反斜杠本身，请使用 \\；如果想插入不换行的空格，请使用  。从 CSV 或 HTML 数据生成 Markdown 表格时，CSV to Markdown 和 HTML to Markdown 会自动处理管道符转义，无需手动担心。

单元格内换行与各平台支持情况

根据 Markdown 表格规范，单元格内不能写入原始换行符。如果需要视觉上的换行，必须直接编写 HTML 标签 <br>。但各平台的支持情况存在差异。

如果表格需要大量可靠的换行，强行塞进 GFM 表格不如使用 HTML <table> 或拆分列更安全。

表格损坏的原因与检查清单

如果表格渲染不正确并显示为文本，请按顺序检查以下项目：

• 表格前后是否有空行 — 如果与前后行紧贴，解析器可能无法识别为表格（在 GitHub 上尤其常见）。
• 是否存在表头行 — GFM 要求必须有表头行。即使不需要表头文本，也必须编写空表头行和分隔行。
• 表头行和分隔行的列数是否一致 — 如果这两行不一致，解析器将完全不识别表格。连字符的数量（-- 或 ---）本身不是错误原因。
• 表头、分隔行和数据行的列数（管道符数量）是否一致 — 如果数据行列数不足，会用空单元格补齐；如果多余，多余部分会被截断。
• 单元格内是否有未转义的管道符 | — 如果有，请改为 \| 或 |。
• 行首是否有不必要的缩进（4 个或更多半角空格） — 可能被误认为代码块。
• 单元格内是否包含代码块或列表等块级元素 — GFM 表格中不允许使用。

如果检查清单无法解决问题，请检查你的渲染器是否支持 GFM 表格扩展。也可参考表格不显示或错乱时的排查方法。

从 CSV / HTML / JSON 自动生成表格

5 行以内的小表格手动编写就足够了，但超过 20 行或列数较多的表格，手动操作时很容易在管道符对齐或转义上出错。根据原始数据格式使用 FormatArc 的工具，可以一次性生成 GFM 兼容的表格。

• 来自 CSV / 电子表格 / Excel 的数据：粘贴到 CSV to Markdown 并运行，即可立即转换为管道符表格。详细步骤参见 CSV 转 Markdown 表格指南。
• 来自现有 HTML（网页表格、Notion 导出、CMS 数据转储等）：将 HTML 代码粘贴到 HTML to Markdown，<table> 标签会被提取并转换为 Markdown 管道符表格。详细方法参见 HTML 转 Markdown 指南。
• 来自 JSON（API 响应或日志数据）：先转换为 CSV 格式，然后传递给 CSV to Markdown 是最可靠的方法。数组、嵌套数据的处理详见 JSON 转 Markdown 表格。
• 如果需要将生成的 Markdown 表格粘贴到不支持 Markdown 的 CMS 或 HTML 邮件中，请使用 Markdown to HTML 进行转换。转换步骤参见 Markdown 转 HTML 指南。

FormatArc 的所有处理都在浏览器内本地完成，因此即使粘贴包含内部数据或客户信息的文本，也不会发送到外部服务器。无需注册或文件上传。

将生成的表格传递给 LLM 提示词时，与相同内容的 HTML 相比，Markdown 表格的 token 消耗更少且可读性更高，有助于保持解析准确性。实测对比详见 LLM 输入用 Markdown 还是 HTML。

Markdown 表格无法实现的事情 — 切换到 HTML 的标准

具有以下需求的表格无法用 GFM 表格实现，需要直接在 Markdown 文档中编写 HTML <table> 标签：

• 需要按行或列合并单元格（rowspan、colspan）
• 需要在单元格内包含列表、多段落或代码块
• 需要以像素或百分比固定列宽
• 需要在表格内部嵌套标题或其他表格

但 GitHub 等平台出于安全原因严格限制表格内部的 HTML 属性。<br> 是允许的，但 <span style="..."> 的 style 属性会被连同属性本身一起删除，因此无法更改字体颜色或大小。

GFM 不支持单元格合并（rowspan / colspan）的原因

GFM 规范的 Tables (extension)在新标签页中打开 在 ABNF 语法级别严格要求管道符分隔语法中“1 行 = 1 行（row）”的结构。因此，从结构上无法表达跨行的单元格合并。这是优先考虑文本本身的可读性和解析器实现简单性的设计，在后续的 CommonMark 扩展讨论中也维持了相同的设计。因此，需要合并的表格被视为超出 GFM 范围，使用 HTML <table> 是实际上的正确解决方案。

使用 HTML <table> 合并的最小代码示例

在 Markdown 文件中直接编写 HTML 标签时，GitHub 等大多数 GFM 渲染器会将其渲染为 HTML 表格。

列方向合并（colspan）：

<table>
  <tr><td colspan="2">期间 (2026)</td></tr>
  <tr><td>4月</td><td>9月</td></tr>
</table>

行方向合并（rowspan）：

<table>
  <tr><td rowspan="2">项目 A</td><td>启动</td></tr>
  <tr><td>交付</td></tr>
</table>

GitHub 允许与删除的 HTML 属性

GitHub 出于安全（防 XSS）目的对表格内部的 HTML 进行消毒（sanitize）处理，不在允许列表中的属性会被整个删除。下表是实际通过 GitHub 的 Markdown 渲染 API（与 README 和 Issue 正文相同的管道）测量得到的结果（测量脚本位于仓库的 scripts/benchmarks/github-table-attributes/）。

如果想通过字体颜色或大小强调特定单元格，可以选择在表格外部放置徽章或图表，使用 Markdown 的 **粗体** 替代，或者将表格截图为图片后插入。

GFM 以外的单元格合并扩展语法（在 GitHub 中不支持）

GitHub 不支持以下语法，但在本地 Markdown 预览或特定工具环境中支持这些独立扩展语法：

• VS Code 扩展 Markdown Preview Enhanced在新标签页中打开 — 使用 > 合并上方单元格，使用 ^ 合并左侧单元格
• Python-Markdown 扩展 mdx_tableau在新标签页中打开 — 在 Markdown 语法内表达 colspan/rowspan
• Pandoc grid table / multiline table在新标签页中打开 — 可使用 +---+---+ 网格形式表达合并

但要在 GitHub README 或 Issue 中完美渲染，不依赖这些工具专属扩展，直接编写标准 HTML <table> 是最安全的。

CommonMark 与表格的关系

纯 CommonMark在新标签页中打开 规范中没有定义表格语法。管道符分隔表格是在 GitHub Flavored Markdown 规范的 Tables (extension) 部分在新标签页中打开 定义的 GFM 专属扩展功能。因此，严格实现 CommonMark 核心规范且不包含表格扩展的解析器会将 | col | 语法输出为普通字符串而不是表格。要确认你使用的环境是否支持 GFM 表格，最好先编写一个简单的 3 行表格进行测试。

常见问题

最小的 Markdown 表格如何编写？

表头行 1 行、分隔行 1 行、数据行 1 行，总共 3 行是最小单位。在 | key | value | 下方写 | --- | --- |，再下方写 | name | FormatArc | 形式。分隔行的连字符每列放 3 个（---）是惯例，但 GFM 规范上 1 个也有效。

如何将单元格留空？

在两个管道符之间留空即为空单元格（| 值 | |）。由于列数必须与表头保持一致，空单元格必须是 | | 形式，不能省略管道符本身。当空单元格位于行首时，务必保留行首的管道符（| | 值 |），以防止部分渲染器丢失第一列。

\| 和 | 应该用哪个？

基本优先使用反斜杠转义 \|。GitHub 官方规范中有明确说明，且在大多数 GFM 渲染器中正常工作。如果特定渲染器无法正确识别 \|，或在编辑器之间复制粘贴时字符损坏，请使用 | 作为后备。

能在单元格内更改字体颜色或大小吗？

仅用 GFM 表格无法更改。包括 GitHub 在内的主要平台出于安全原因过滤表格内部的 style 属性，因此即使编写 <span style="..."> 也会被忽略样式。如果必须指定格式，请考虑将表格移出或使用 HTML 渲染环境。

表格列宽有标准吗？

Markdown 没有直接指定列宽的语法，渲染器会根据单元格内容长度自动调整。实际工作中，如果考虑 PC 和移动设备两种环境，建议将列数控制在 5~6 列以内。超过此数量会出现水平滚动，降低可读性。

能进行单元格合并（rowspan / colspan）吗？

GFM 表格语法本身无法实现。需要合并单元格的表格必须在 Markdown 文档内直接编写 HTML <table> 标签。

表格不显示，直接输出 | col | 文本。为什么？

最常见的原因是表格前后缺少空行、缺少表头行、表头行和分隔行列数不匹配，或者渲染器是不支持 GFM 表格扩展的纯 CommonMark 环境。请参考正文中的“表格损坏的原因与检查清单”。

总结

GFM Markdown 表格是使用管道符（|）和连字符（-）简洁编写表格的有用工具。只要掌握对齐指定、管道符转义、空单元格处理等基本规则，在编写 GitHub README 或文档时就能轻松构建整洁的表格。

在处理行数较多或复杂的电子表格数据时，建议使用 CSV to Markdown 转换器自动生成 Markdown 表格，可大幅减少输入错误并节省工作时间。