先看诊断顺序 — 按这个顺序排查
Markdown 表格不显示或显示错乱时，解析器不会给出任何报错。没有被识别为表格就静默降级为普通段落；单元格分隔被误读就静默输出列错位的表格。既然没有报错信息，只能自己按顺序逐项排查。
需要检查的项目共 5 项。按"最可靠地破坏表格"和"排查成本最低"排序：
- 表头行与分隔行的列数是否一致（列数不匹配是规范层面唯一能彻底让表格识别失败的语法条件）
- 单元格中是否混有未转义的管道符
|（包括内联代码内部） - 表格上方是否有空行
- 当前渲染器是否支持 GFM（GitHub Flavored Markdown）表格
- 是否属于语法之外的环境问题（Jupyter 单元格类型、平台 CSS 等）
快速缩小范围的办法是先贴一个最小表格试试。
| A | B |
| --- | --- |
| 1 | 2 |
如果这 3 行都渲染不出表格，问题出在渲染器或环境（跳到症状 1 后半部分或症状 5）。如果能正常渲染，问题在你自己的表格写法上（从症状 1 开始逐项排查）。
想确认 GFM 解析器如何解读你的表格，可以把内容贴到 Markdown to HTML 转换器。它基于 marked 的 GFM 解析器在浏览器内输出 HTML，看到 <table> 标签就说明解析成功。粘贴的内容不会上传到服务器。不过它只验证 GFM 系解析器的行为，不能完整复现 Notion、内部 wiki 等特定平台的渲染逻辑。
本文聚焦故障排查。如果想从头确认表格的正确写法，请参考 Markdown 表格语法。
症状 1：表格不显示 — 被当作普通文本
管道符分隔的文本没有渲染成表格，而是显示为一段普通文字。这说明解析器没有把这块内容识别为表格。
表头行与分隔行列数不一致
这是唯一能确定性地让表格识别失败的语法条件。GFM 规范明确规定：分隔行的列数与表头行不一致时，该块不视为表格。不会报错，直接降级为段落。
下面是一个坏掉的例子。表头有 3 列，分隔行只有 2 列。
| 姓名 | 邮箱 | 权限 |
| --- | --- |
| 小明 | xiaoming@example.com | admin |
把分隔行的列数补齐到与表头一致就能识别。
| 姓名 | 邮箱 | 权限 |
| --- | --- | --- |
| 小明 | xiaoming@example.com | admin |
数列数只需要看表头行和分隔行这 2 行。数据行列数多或少不会导致识别失败（那属于症状 2）。
表格上方没有空行
段落之后紧接表格、中间没有空行时，部分解析器不会识别为表格。实测结果（2026-07-15，复现脚本在 scripts/benchmarks/markdown-table-parsers/）：GitHub 官方渲染器（Markdown API）、marked 18.0.5、remark-gfm 4.0.1 在没有空行的情况下都能识别表格，但也有要求空行的实现或平台。加一行空行就能解决，是成本最低的修复，建议在检查完列数之后立即尝试。
列表项中的表格
在无序列表项或引用块内写表格时，规则与独立表格不同。无序列表标记 - 由短横线和空格组成共 2 个字符，有序列表标记 1. 由数字、句点和空格组成共 3 个字符。要让表格保持在 <li> 内部，缩进必须达到该标记的宽度。这是在本站 CSV to Markdown 流水线中用 remark 4.0.1 + remark-gfm 4.0.1 实测得出的结果（scripts/benchmarks/markdown-table-in-containers/）。
| 写法 | 是否识别为表格 | 是否进入 <li> 内部 |
|---|---|---|
- item 之后、缩进 0、无空行 | 否 | — |
- item 之后、缩进 0、有空行 | 是 | 否（被移出 <ul>，成为兄弟块） |
- item 之后、缩进 1、有空行 | 是 | 否 |
- item 之后、缩进 2、无空行 | 是 | 是 |
- item 之后、缩进 2、有空行 | 是 | 是 |
1. item 之后、缩进 2、有空行 | 是 | 否 |
1. item 之后、缩进 3、有空行 | 是 | 是 |
缩进不足且没有空行时，本该是表格的行被当作前一段落的延续而吞掉，表格不生成（第 1 行）。加了空行后表格本身会生成，但缩进不够时列表在此处结束，表格作为列表外部的兄弟块渲染（第 2、3、6 行）。有序列表标记比无序列表多 1 个字符，所以缩进 2 对无序列表能进入 <li>，对有序列表则不够（第 6 行与第 7 行的差别）。要把表格稳定地放在 <li> 内部，缩进宽度应与列表标记宽度一致。
引用块中的表格
引用块的 > 前缀加在哪些行上，结果差别很大。同一批实测（scripts/benchmarks/markdown-table-in-containers/）：
| 写法 | 是否识别为表格 | 数据行 |
|---|---|---|
> 只在第 1 行 | 否（3 行合并为 1 段） | — |
> 只在表头和分隔行 | 是 | 消失（只生成了 <thead>，数据行变成了引用块外的段落） |
> 在所有行 | 是 | 正常保留 |
特别需要警惕第 2 行。只在表头和分隔行加 > 就足以让 GFM 表格扩展识别出一个表格并生成 <table>，但没有 > 的数据行不属于引用块，会作为普通段落文本掉到表格外面。没有任何报错或警告，表格"看起来在"但内容是空的，很难察觉。在引用块内写表格时，务必确认包括数据行在内的每一行都带 > 前缀。
"短横线少于 3 个就不行"是误解
部分文档或博客文章说"分隔行每列必须 3 个以上短横线"，但 GFM 规范没有最短数量限制。实测（2026-07-15，scripts/benchmarks/markdown-table-parsers/）：GitHub 官方渲染器、marked 18.0.5、remark-gfm 4.0.1 每列只用 1 个短横线（| - | - |）也能正常渲染表格。
GitHub 官方文档写"3 个以上"、规范没有数量规定、实现接受 1 个——三处不一致。把 3 个当作可读性惯例即可。不要花时间在短横线数量上反复试错，先查列数和空行。
唯一的例外是省略外层管道符且只用 1 个短横线的组合，见症状 4。
渲染器不支持 GFM 表格
表格不是 Markdown 核心规范的一部分。纯 CommonMark在新标签页中打开 规范中没有表格语法定义，表格是 GFM 的扩展功能。未启用扩展的严格 CommonMark 渲染器，无论表格写得多正确都不会渲染。背景详见 CommonMark 规范与 GFM 的区别。
部分博客平台或 CMS 的 Markdown 支持范围有限，不包含表格。请查看所用平台的文档，确认表格是否在支持的语法列表中。语法本身没问题但编辑器或环境不渲染的情况，见症状 5。
AI 生成的表格被粘贴在代码围栏内
复制 ChatGPT 或 Gemini 输出的表格时，有时整个表格被三行反引号（代码围栏）包裹，导致渲染为代码块而非表格（OpenAI Developer Community 报告在新标签页中打开）。删掉首尾的反引号行后就能正常识别。
症状 2：列错位或单元格被意外拆分
表格被识别了，但列位置错乱，或者一个单元格的内容被拆成了两个。
单元格内的管道符
管道符 | 是列分隔符，在单元格内容中直接写会让那一处变成列边界。下面这个表格本想在第一列显示 cmd1 | cmd2 这个命令，结果 cmd1 和 cmd2 分到了不同的列，超出表头列数（2 列）的"用管道连接"被静默截断。
| 命令 | 说明 |
| --- | --- |
| cmd1 | cmd2 | 用管道连接 |
用 \|（反斜杠转义）或 |（HTML 数字字符引用）替换后就能收进一个单元格。
| 命令 | 说明 |
| --- | --- |
| cmd1 \| cmd2 | 用管道连接 |
内联代码中的管道符也不会被保护
直觉上反引号内的内容应该被保护，但实际上管道符在反引号内也不会被保护。Markdown 解析器先按管道符做单元格拆分，再解析内联格式。
| 命令 | 说明 |
| --- | --- |
| `a | b` | 内联代码区域 |
这一行被拆成 `a 和 b` 两个单元格，反引号没有配对，原样显示。GFM 表格扩展规范在新标签页中打开 规定：即使在内联代码 span 内，包含管道符也必须转义。
解决方法是内联代码内也用反斜杠转义：
`a \| b`— 内联代码内也写\|。在 GitHub、marked、remark-gfm 上均能正确渲染为代码a | b|在内联代码内不可用。反引号内不解析字符引用，会原样显示 6 个字符- 总结：普通单元格文本中
\|和|都可以用；内联代码中只能用\|
可转义的符号不止管道符。星号、尖括号等特殊符号的转义方法见 Markdown 转义字符一览。
全角符号混入 — 中文输入法的专属陷阱
使用中文输入法时，全角竖线 ｜ 和半角竖线 | 在视觉上极为相似。误输入全角竖线后，解析器不会把它当作列分隔符，结果就是列数对不上、表格识别失败。
| 姓名｜部门｜职位 |
| --- | --- | --- |
| 张三 | 技术部 | 工程师 |
表头中的全角竖线 ｜ 不是列分隔符，解析器看到整行只有一个半角管道符（或没有），列数与分隔行不匹配，表格降级为段落。检查方法：把光标放在疑似位置，看输入法状态是否在全角模式；或者直接复制该行到文本编辑器中查看字符编码。
全角空格 也是常见隐患。在分隔行中误输入全角空格会破坏分隔符边界，导致列数无法对齐。
| 列A | 列B |
| --- | --- |
分隔行第 1 列和第 2 列之间的 是全角空格，解析器无法将其识别为有效的分隔符边界。切换到半角输入模式，确认所有管道符和空格都是半角字符即可。
全角逗号 ， 混入分隔行也会导致类似问题。虽然全角逗号通常出现在单元格文本而非分隔行中，但在手动编辑时也可能被误输入。
数据行列数不匹配导致错位
数据行的列数与表头不同时，表格不会识别失败，但会表现为视觉错位。实测：列少的行用空单元格补齐，列多的行超出部分被静默丢弃。感觉"最后一列的值消失了"时，检查该行的前半部分是否混入了多余的管道符（多出一列）。
手动逐格转义管道符、校对列数很繁琐。源数据如果在 CSV 或电子表格中，可以贴到 CSV to Markdown 转换器，让工具自动处理列数对齐和管道符转义。
症状 3：单元格内换行导致表格断裂
Markdown 表格语法没有单元格内换行的写法。在单元格中间按回车，从下一行开始会被解析为新的数据行，表格断裂或整体下移。
解决办法是在单元格内直接写 HTML 的 <br> 标签。
| 项目 | 说明 |
| --- | --- |
| 设置 A | 第 1 行<br>第 2 行 |
<br> 不是 Markdown 语法而是原生 HTML，在渲染器禁用或过滤 HTML 标签的环境中不生效。这种情况下放弃单元格内换行，改为拆句或拆行。对齐、空单元格、换行与管道符转义的对应写法整理在 GFM 表格速查表。
症状 4：GitHub 上正常但其他平台出错
同一份 Markdown 在不同解析器下结果可能不同。实测中最典型的差异是"省略外层管道符 + 1 个短横线"的组合。
A | B
- | -
1 | 2
分隔行行首是 - （短横线 + 空格），解析器会在此处分歧：是当作列表标记还是表格分隔行。GitHub 和 remark-gfm 不识别为表格而当作列表处理，marked 则渲染为表格（2026-07-15 实测，scripts/benchmarks/markdown-table-parsers/）。省略外层管道符时，短横线至少用 2 个（-- | --）。在行首和行尾都加上管道符（| A | B |）则不存在此问题。
"本地预览正常但发布后出错"的症状，多数源于这类解析器差异或平台 GFM 支持范围不同。可以用最小表格测试配合 Markdown to HTML 转换器 的 HTML 输出对比来定位具体是哪个环节出了问题。
症状 5：语法正确但特定编辑器或环境不显示
所有语法检查都通过了仍然不显示时，怀疑渲染环境而非表格本身。
- VS Code Jupyter 扩展：有报告称 Markdown 单元格中正确的表格渲染为空白（microsoft/vscode-jupyter #16043在新标签页中打开）。另外单元格类型仍为 Code 时 Markdown 不会渲染，确认已切换为 Markdown 单元格
- Obsidian：部分版本中表格上方没有空行时不渲染（Obsidian 论坛报告在新标签页中打开），是症状 1 中"表格上方缺空行"在特定编辑器中的具体表现
- Prettier 等自动格式化工具：保存时自动改写表格格式，可能破坏换行或转义（Atlassian Community 案例在新标签页中打开）。临时禁用格式化器确认问题是否消失
全部语法检查通过仍未解决时，问题在环境。尝试升级编辑器版本、切换扩展或自动格式化设置、用其他预览工具打开。
重建比重修更快的时候
几十行的坏表格逐个管道符排查修复，效率远不如从源数据重新生成。源数据在 CSV 或电子表格中时，3 步完成：
- 将源数据复制为 CSV（从 Excel 或电子表格直接复制单元格区域即可）
- 贴入 CSV to Markdown 转换器
- 复制生成的 Markdown 表格替换坏表格
列数对齐、管道符转义、分隔行生成都由工具自动处理。转换全部在浏览器内完成，数据不会发送到外部服务器，包含内部数据的表格也能放心使用。详细的转换步骤与常见问题见 CSV 转 Markdown 表格指南。如果想把重建的表格转成 HTML 确认渲染效果，可以参考 Markdown 转 HTML 在线工具。
总结 — 记住诊断顺序
- 表格完全不显示时：表头与分隔行列数一致 → 表格上方加空行 → 渲染器是否支持 GFM 表格
- 列错位或被拆分时：单元格管道符转义（
\|） → 内联代码内管道符 → 全角竖线或全角空格混入 → 数据行列数差异 - 数据行列数不匹配：列少补空、列多截断，但不会导致识别失败
- 短横线数量：外层管道符存在时 1 个就够，不必纠结数量
想验证表格解析行为，用 Markdown to HTML 转换器 在浏览器中查看 HTML 输出是最快的方法；想彻底重建表格，用 CSV to Markdown 转换器 从源数据生成最可靠。
常见问题
markdown 表格不显示的最常见原因是什么？
表头行与分隔行的列数不一致。GFM 规范规定列数不同时不识别为表格，直接降级为段落，不会报错。把分隔行列数补齐到与表头一致即可解决大部分情况。
全角竖线为什么会导致表格不显示？
全角竖线 ｜ 不是 GFM 表格规范中的列分隔符。混入表头行或分隔行后，解析器看到的列数与实际不符，表格识别失败，整块降级为普通段落。切换到半角输入模式，确认所有管道符都是半角 | 即可。
单元格内换行怎么办？
Markdown 表格语法不支持单元格内换行。直接在单元格内写 HTML 的 <br> 标签。注意部分渲染器会过滤 HTML 标签，此时 <br> 不生效。
分隔行短横线必须 3 个以上吗？
不需要。GFM 规范没有最短数量限制。实测 1 个短横线即可正常渲染。唯一需要注意的是省略外层管道符且只用 1 个短横线时，部分解析器会误判为列表（见症状 4）。