先診斷 — 按這個順序確認
Markdown 表格沒有顯示、或者看起來壞掉了，解析器不會給你錯誤訊息。表格沒被識別的時候，它會被當成普通段落直接顯示；儲存格的邊界被誤讀的時候，欄位會默默錯位。沒有錯誤訊息可以參考，你就必須自己依序排除原因。
需要確認的項目有 5 個。按照「確實會把表格弄壞」以及「確認成本由低到高」的順序排列：
- 標題行與分隔行的欄位數是否一致（不一致是在規格層面導致表格無法識別的唯一語法條件）
- 儲存格內是否混入了未跳脫的管線符號
|（包含行內程式碼區塊） - 表格正前方是否有一行空白
- 你使用的渲染器是否支援 GFM 表格
- 是否不是語法問題，而是環境問題（Jupyter 儲存格型別、平台 CSS 等）
最快切分問題的方法是貼一個最小的 3 行表格進去試：
| A | B |
| --- | --- |
| 1 | 2 |
如果這 3 行沒有變成表格，問題不在你的表格寫法，而在渲染器或環境（跳到症狀 1 後半段，或症狀 5）。如果正常顯示為表格，問題就在你表格的寫法上（從症狀 1 開始依序確認）。
想確認 GFM 解析器到底怎麼讀你的表格，可以貼到 Markdown 轉 HTML，marked 基礎的 GFM 解析器產生的 HTML 會直接在瀏覽器中顯示。輸出裡有 <table> 標籤就代表解析成功。貼上不會上傳到任何伺服器。不過這只是確認 GFM 系解析器的行為，不等於完全重現 Notion、公司 wiki 等特定平台的渲染。
本文聚焦在除錯。如果你想從零開始學表格語法，可以參考 GFM 表格語法速查。
症狀 1: 表格不顯示 — 當成普通文字
以管線分隔的文字行直接顯示為一段連續文字，沒有表格邊框，沒有欄位分隔。這表示解析器沒有把這個區塊識別為表格。
標題行與分隔行的欄位數不一致
這是唯一一個在規格層面確定會讓表格無法被識別的語法條件。GFM 規格明確規定：如果分隔行的欄位數與標題行不同，該區塊不會被當作表格處理。不會有錯誤訊息，會直接回落為普通段落。
壞掉的例子：標題行有 3 欄，但分隔行只有 2 欄。
| 姓名 | 郵件 | 權限 |
| --- | --- |
| 小明 | ming@example.com | admin |
把分隔行的欄位數對齊到標題行，立刻就能被識別：
| 姓名 | 郵件 | 權限 |
| --- | --- | --- |
| 小明 | ming@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 在沒有空行的情況下都能識別表格，但確實存在要求空行的實作與平台。加一行空行是最便宜的確認方式，建議在檢查完欄位數之後馬上試。
全形管線符號 — 繁體中文輸入法的常見陷阱
這是繁體中文使用者特別容易踩的坑。在 zh-TW 輸入法下，如果輸入法停在中文模式，按管線鍵時輸出的其實是全形管線 ｜（U+FF5C），而不是半形 |（U+007C）。這兩個字元在多數字型下長得幾乎一樣，但 GFM 解析器只認半形的 |。
全形管線 ｜ 比半形 | 寬，在等寬字型中佔一個全形字元的空間。但跟中文文字混排的時候，視覺差異非常小，你很難一眼看出來。同樣的道理，全形減號 －（U+FF0D）如果替換了分隔行裡的半形減號 -（U+002D），整行就不會被識別為分隔行。
下面這段每一行的開頭和結尾都是全形管線 ｜（U+FF5C），不是半形 |（U+007C）：
｜ 名稱 ｜ 數值 ｜
｜ －－－ ｜ －－－ ｜
｜ 甲 ｜ 1 ｜
把游標放在行首，如果看到一個佔全形寬度的符號，很可能就是全形管線。修正方法：把輸入法切換到英文（半形）模式，重新輸入 | 和 -。表格很長的話，用搜尋取代把全形 ｜ 替換成半形 |、全形減號 － 替換成半形 - 即可。
全形與半形的對照：
| 用途 | 正確（半形） | 常見錯誤（全形） | Unicode |
|---|---|---|---|
| 管線（欄位分隔） | ` | ` U+007C | ｜ U+FF5C |
| 減號（分隔行） | - U+002D | － U+FF0D | 分隔行 |
| 逗號 | , U+002C | ， U+FF0C | 全形逗號不會當成分隔符，但混在欄位內容裡會造成視覺混淆 |
列表項目內的表格
在項目符號清單或引用區塊內放表格時，規則跟獨立表格不同。項目符號標記 - 是連字號加空格共 2 個字元；編號清單標記 1. 是數字、句號、空格共 3 個字元。要讓表格留在 <li> 元素裡面，縮排至少要和標記寬度一樣寬。以下是 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 個字元的標記寬度，所以項目符號裡能收進 <li> 的 2 格縮排，在編號清單中就不夠（第 6 行與第 7 行的差異）。要穩定地把表格放在 <li> 裡，把縮排對齊到清單標記的寬度。
引用區塊內的表格
引用區塊的 > 符號加在哪幾行，結果差很多。同一組實測（scripts/benchmarks/markdown-table-in-containers/）：
| 寫法 | 是否識別為表格 | 資料行 |
|---|---|---|
> 只加在第 1 行 | 否（3 行合成 1 個段落） | — |
> 只加在標題行與分隔行 | 是 | 消失（只生成 <thead>，資料行跑到引用區塊外的段落） |
> 加在每一行 | 是 | 正常保留 |
最需要注意的是第 2 行。只在標題行和分隔行加 > 的時候，GFM 表格擴展會只用這兩行就識別出表格並生成 <table>，但沒有 > 的資料行不屬於引用區塊，會以普通段落文字的形式掉到表格外面。沒有錯誤也沒有警告，表格看起來在但內容是空的。在引用區塊裡寫表格時，務必確認每一行包含資料行都加了 >。
「至少要 3 個減號」大多是誤傳
有些文章寫著「分隔行每欄必須有 3 個以上的連字號」，但 GFM 規格沒有規定最低數量。GitHub 正式渲染器、marked 18.0.5、remark-gfm 4.0.1 全都可以用 1 個減號（| - | - |）正常渲染表格（2026-07-15 實測，scripts/benchmarks/markdown-table-parsers/）。
混亂的來源是三方不一致：GitHub 官方文件寫「3 個以上」，規格沒有規定數量，實作接受 1 個。把 3 個當作可讀性慣例就好。別浪費時間改減號數量，先確認欄位數和空行。
唯一的例外是省略外側管線、只用 1 個減號的組合，這在症狀 4 說明。
渲染器不支援 GFM 表格
表格不是 Markdown 的核心規格。純 CommonMark在新分頁中開啟 規格沒有表格語法的定義，表格是 GFM 的擴展功能。沒有套用表格擴展的 CommonMark 渲染器，不管寫得多正確都不會變成表格。兩套規範的差異背景，整理在 CommonMark 與 GFM 的差異。
有些部落格平台或舊版 CMS 支援的 Markdown 語法有限，不包含表格。查一下你使用的平台說明文件，確認表格是否在支援語法清單中。
AI 生成的表格被包在程式碼塊裡
從 ChatGPT 或 Gemini 複製表格時，有時整張表格被程式碼圍欄（行首的 3 個反引號）包起來，結果顯示為程式碼塊而不是表格（OpenAI Developer Community 的報告在新分頁中開啟）。把首尾的反引號行刪掉，就能正常解析為 GFM 表格。
症狀 2: 欄位移位、儲存格被拆開
表格有顯示，但欄位位置不對，或者一個儲存格的內容被拆成兩個。
儲存格內的未跳脫管線
管線 | 是欄位分隔符號，所以把它寫在儲存格內容裡的時候，解析器會在該位置切分欄位。下面的表格原本想在第一欄顯示 cmd1 | cmd2 這個命令，結果 cmd1 和 cmd2 被拆到不同的儲存格，超出台頭 2 欄的「以管線連結」被默默丟掉。
| 命令 | 說明 |
| --- | --- |
| cmd1 | cmd2 | 以管線連結 |
把管線替換成 \|（反斜線跳脫）或 |（HTML 數字字元引用），就能收在一個儲存格裡：
| 命令 | 說明 |
| --- | --- |
| cmd1 \| cmd2 | 以管線連結 |
行內程式碼（反引號）內的管線也不被保護
直覺上會以為反引號包起來就安全了，但並不會。表格的儲存格切分（管線解析）在行內格式（反引號）解析之前執行，所以行內程式碼內的管線一樣會被當成欄位分隔符。
| 命令 | 說明 |
| --- | --- |
| `a | b` | 行內程式碼區域 |
這一行會被拆成 `a 和 b` 兩個儲存格，反引號配對不上，直接以原始文字顯示。GFM 表格擴展規格在新分頁中開啟 規定：要在儲存格內容中包含管線，即使在行內程式碼內也必須跳脫。
修正方法是在行內程式碼裡也用反斜線跳脫：
- 寫成
`a \| b`，\|在行內程式碼內也有效。GitHub、marked、remark-gfm 全部正確渲染為a | b的程式碼 |在行內程式碼內不能用。反引號內的字元引用不會被展開，會原樣顯示|這 6 個字元- 總結：一般儲存格文字可以用
\|和|，行內程式碼內只能用\|
能跳脫的記號不只直欄。包含星號、山鉤在內的完整清單，參考 Markdown 跳脫字元與特殊符號。
資料行欄位數多寡造成偏移
資料行的欄位數跟標題不同，不會讓表格無法識別，但會以外觀錯位的形式表現。實測結果：欄位不夠的行會用空白儲存格補滿，多出來的欄會被默默丟掉。覺得「最後一欄的值消失了」的時候，檢查那一行前面是不是多了一個管線（多出來一欄）。
手動跳脫管線、逐行檢查欄位數是很耗神的。原始資料如果在 CSV 或試算表裡，貼到 CSV 轉 Markdown 就能自動處理欄位一致性和管線跳脫。
症狀 3: 儲存格內換行導致表格壞掉
Markdown 表格語法沒有儲存格內換行的寫法。在儲存格中間按 Enter，從那之後會被當成新的表格行，表格會中斷或者被擠到其他行。
避開的方式是在儲存格內直接寫 HTML 的 <br> 標籤：
| 項目 | 說明 |
| --- | --- |
| 設定 A | 第 1 行<br>第 2 行 |
不過 <br> 不是 Markdown 語法，是原生 HTML 的避讓手段。渲染器如果因為安全理由停用或清理 HTML 標籤，<br> 就不會生效。那種環境下，比較務實的做法是把句子拆開或者分行。
症狀 4: GitHub 上正常，其他平台壞掉
同一份 Markdown，不同的解析器可能解析出不同結果。實測確認到的代表性差異是「省略外側管線＋1 個減號」的組合：
A | B
- | -
1 | 2
分隔行的行首是 - （連字號＋空格），解析器會分歧：GitHub 和 remark-gfm 把它當作清單符號、不生成表格；marked 則渲染為表格（2026-07-15 實測，scripts/benchmarks/markdown-table-parsers/）。如果用了省略外側管線的寫法，減號至少寫 2 個（-- | --）。行首行末都加上管線（| A | B |）的話，這個問題根本不會發生。
「本機預覽正常但發布到平台就壞」這種症狀，絕大多數是這種解析器差異，或者是症狀 1 提到的 GFM 支援缺口。平台之間的差異（Notion 不支援對齊冒號或 <br> 等），可以用最小表格測試加上 Markdown 轉 HTML 的 HTML 輸出來比對確認。各平台的對應差異整理在 Markdown 表格語法。
症狀 5: 語法正確但特定編輯器或環境不顯示
所有語法檢查都通過了還是壞的，該懷疑的是渲染環境本身，不是表格寫法。症狀 4 是解析器之間的差異，這是語法完全正確但因為環境原因不顯示的情況。
- VS Code Jupyter 擴充功能：Markdown 儲存格中寫了正確的表格卻顯示空白，已有報告（microsoft/vscode-jupyter #16043在新分頁中開啟）。另外，如果儲存格型別是 Code，Markdown 本身就不會渲染，確認是否已切換為 Markdown 儲存格（這跟 #16043 是不同的原因）
- Obsidian：部分版本在表格正前方沒有空行時不渲染表格（Obsidian 論壇報告在新分頁中開啟）。這是症狀 1 中「表格正前方沒有空白行」在特定編輯器中的具體表現
- Prettier 等自動格式化工具：每次儲存時自動重組表格格式，把換行或跳脫弄壞的案例（Atlassian Community 案例在新分頁中開啟）。暫時停用格式化器確認問題是否消失
所有語法檢查都通過的話，原因在環境不在表格。嘗試更新編輯器、切換擴充功能或自動格式化、在別的預覽器開啟。
重新生成比修復更快的時候
在壞掉的 30 行表格裡一根一根數管線去修，通常不如從原始資料重新生成快。原始資料在 CSV、Excel、或試算表的話，不到一分鐘就能完成：
- 把原始資料以 CSV 格式複製（Excel 或試算表的儲存格範圍直接複製也可以）
- 貼到 CSV 轉 Markdown
- 把自動生成的 Markdown 表格複製過去覆蓋壞掉的那個
欄位數一致性、管線跳脫、分隔行生成全部由工具處理。轉換完全在瀏覽器內完成，資料不會傳送到外部伺服器，所以包含內部資料的表格也能安心使用。從 CSV 轉換的完整步驟，參考 CSV 轉 Markdown 表格：GFM 表格轉換指南；轉完的表格要再轉成 HTML，參考 Markdown 轉 HTML 完整指南。
常見問題
Markdown 表格不顯示最常見的原因是什麼？
標題行與分隔行的欄位數不一致是最常見的原因。GFM 規格規定欄位數不同的話，解析器不會報錯，直接當作普通段落處理。把分隔行的欄位數對齊到標題行，大部分情況就解決了。
儲存格內要換行怎麼做？
Markdown 表格規格沒有換行語法，必須直接在儲存格內容中寫 HTML 的 <br>。不過限制原生 HTML 的平台可能不生效。
行內程式碼內的管線 | 為什麼會拆表格？
因為 Markdown 解析器在解析行內程式碼格式之前，就先以管線符號切分儲存格。即使在反引號裡面，要把管線當作儲存格內容顯示，也必須寫成 \|。
表格正前方一定要加空白行嗎？
部分解析器或編輯器（如 Obsidian）在表格前沒有空行時，會把表格當成上一段落的延續，不渲染為表格。表格前後各留一空行最安全。
全形管線 ｜ 和半形管線 | 有什麼差別？
半形管線 |（U+007C）是 GFM 表格的欄位分隔符號。全形管線 ｜（U+FF5C）是 CJK 全形符號，GFM 解析器不認它。繁體中文輸入法在中文模式下按管線鍵容易出全形，建議切換到英文模式後再按。全形符號比半形寬，跟中文混排時視覺差異很小，不容易注意到。
整理 — 記住診斷順序就好
表格不顯示的時候：標題行與分隔行的欄位數、表格正前方的空白行、全形管線 ｜ 是否混入、渲染器的 GFM 支援。欄位移位的時候：儲存格內的管線（\| 跳脫，行內程式碼也包括）、資料行欄位數。減號數量除了「省略外側管線」的邊緣情況之外，不是原因。
診斷用 Markdown 轉 HTML 確認 HTML 輸出最快捷，修復用 CSV 轉 Markdown 重新生成最可靠。