Markdown 表格語法：對齊、儲存格內換行與轉義總整理

先講結論

Markdown 表格只需要 pipe 記號 | 和連字號 - 就能寫。

| 姓名 | 信箱 | 權限 |
| --- | --- | --- |
| 王小明 | xiaoming@example.com | admin |
| 李美玲 | meiling@example.com | viewer |

手寫太麻煩的話，把 CSV 貼到 CSV 轉 Markdown 轉換器 就能直接轉換。以下詳細說明語法。

基本語法 — pipe 與連字號

Markdown 表格由三個部分組成。

1. 表頭列 — 用 pipe | 分隔各欄位名稱
2. 分隔列 — 用連字號 - 排列，分隔表頭與資料（慣例上寫 3 個）
3. 資料列 — 每個儲存格用 pipe 分隔

| 項目 | 值 |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

列首和列尾的 pipe 可以省略，但為了可讀性通常會加上。不需要手動調整各欄寬度，渲染時會自動調整。

pipe 與分隔列的結構

pipe 記號 | 是用來分隔欄位的記號。分隔列（也稱表頭分隔行、dash 行）由連字號 - 組成，告訴渲染器表頭與資料的邊界在哪裡。

關於 pipe 和連字號，需要記住以下規則：

• 每欄寫 3 個連字號（---）只是慣例，不是解析器的規則。GFM 規格沒有規定最小數量，-- 甚至只寫 1 個 -，GFM 渲染器都會當成表格繪製（已在 marked 18.0.5 / remark-gfm 4.0.1 驗證）。寫 3 個是為了可讀性
• 真正會弄壞表格的，是表頭列和分隔列的欄位數不一致。GFM 規格明確規定欄位數不一致時不會被識別為表格
• 列首和列尾的 pipe 可以省略。| A | B | 和 A | B 的渲染結果相同
• 對齊冒號（:---、:---:、---:）只能放在分隔列。資料列不寫
• GFM 中表頭列是必須的。CommonMark 核心規格沒有表格定義，所以沒有表頭的表格只存在於各家擴充中

如果表格沒有渲染出來，首先檢查表頭列和分隔列的欄位數是否一致。不一致的話根本不會被識別為表格。其次常見的原因是表格前面缺少空行，連字號數量不對的情況幾乎不會發生。

對齊設定 — 左對齊、置中、右對齊

在分隔列加入冒號 : 就能控制欄位的對齊方式。

| 商品 | 數量 | 單價 |
| :--- | :---: | ---: |
| 蘋果 | 3 | 120 |
| 柳丁 | 10 | 80 |

數字欄設成右對齊後，數位就會對齊，比較容易閱讀。

GFM（GitHub Flavored Markdown）的表現

GitHub、GitLab、Notion、Obsidian、Jira、Confluence 等主要平台都支援 GitHub Flavored Markdown（GFM）的表格語法。上面介紹的語法可以直接使用。

GFM 表格中值得記住的幾點：

• 表頭列必須。沒有表頭的表格在 GFM 中無法建立
• 分隔列的連字號寫 3 個（---）是慣例，規格上少於 3 個也有效
• 儲存格內可以使用行內格式（程式碼、連結、刪除線等）
• 表格前後如果不加空行，解析器可能不把它當成表格

各平台的 pipe 表格支援

表格的三個基本元素——pipe | 表格、分隔列的冒號對齊（:---）、儲存格內換行用的 <br>——在各平台的支援情況不同。

關於表格的補充說明：

• GitHub 依據 GitHub Flavored Markdown 規格的 Tables (extension) 章節在新分頁中開啟定義 pipe 表格和分隔列的冒號對齊。儲存格以行內內容解析，因此 <br> 等行內 HTML 被允許，GitHub 會把它當作儲存格內換行來繪製
• GitLab Flavored Markdown 同樣文件化了 pipe 表格與對齊語法，官方文件明確指出可以在儲存格內使用 <br> 標籤來換行
• Obsidian 支援 pipe 表格和冒號對齊，實際上會把 <br> 標籤當作儲存格內換行來繪製
• Notion 可以匯入或貼上 pipe 表格，但不以 GFM 渲染，而是轉成自己的表格區塊。Notion 表格沒有欄位對齊，所以對齊冒號（:---）不會影響外觀，儲存格內的 <br> 也不會變成換行

具體規則定義在 GitHub Flavored Markdown 規格的 Tables (extension) 章節在新分頁中開啟。純 CommonMark在新分頁中開啟 沒有表格語法的定義，所以表格在技術上是 GFM 的擴充功能。只嚴格實作 CommonMark 而不採用擴充的渲染器不會把內容顯示為表格。CommonMark 與 GFM 的規格差異詳見 CommonMark 與 GFM Markdown Spec 的差異；想快速查詢 GFM 表格語法可參考 GFM Table 快速參照。

分隔列的實際行為 — 4 個渲染器驗證（GitHub / marked / remark-gfm / CommonMark）

GFM Tables 擴充只定義分隔列是「內容僅為連字號（-）、前後可加冒號（:）的儲存格」，沒有在任何地方寫明連字號的最小數量。GitHub 自己的文件說「每欄至少 3 個連字號」，但規格沒有這條規則，GitHub 的渲染器接受 1 個就夠。規格本身的對齊範例也只用了 1 個連字號的 :-:。

為了確認這個說法，把同一組邊界案例分別送到 GitHub 的正式渲染器（透過 Markdown API）、marked、remark-gfm、沒有擴充的嚴格 CommonMark 管線。重現腳本在 repository 的 scripts/benchmarks/markdown-table-parsers/。2026-07-15 實測，marked 18.0.5 / remark-gfm 4.0.1 / remark-parse 11.0.0：

有 3 個值得注意的發現：

• 連字號數量不影響是否被繪製為表格。在 GitHub / marked / remark-gfm 中，1 個和 3 個的行為完全一樣，「3 個」只是可讀性的慣例，不是必要条件
• 唯一有實質差異的解析器行為出現在表格倒數第二列。省略外側 pipe 並只寫 1 個連字號時，分隔列以 - 開頭，GitHub 和 remark-gfm 會把它讀成清單標記，marked 則當成表格處理。如果要省略外側 pipe，連字號至少留 2 個
• 在任何渲染器中，只要分隔列的欄位數和表頭不一致，表格就一定會壞。不會被識別為表格，會 fallback 成段落，也不會有任何錯誤訊息

pipe 與特殊字元的轉義

儲存格內直接寫 pipe | 會被誤認成欄位分隔，表格就會壞掉。安全的寫法有兩種：

| 指令 | 意義 |
| --- | --- |
| cmd1 \| cmd2 | 用反斜線轉義 |
| cmd1 | cmd2 | 用 HTML 實體表示 |

• \|（反斜線轉義）在 GitHub、GitLab、Notion、Obsidian 等主要 GFM 渲染器中都有效
• |（HTML 數字字元參考）是渲染器沒正確處理 \| 時的備援，跨編輯器複製時不容易出錯

儲存格內要顯示反斜線本身時寫 \\。要放不換行的空白時用  。要確認哪些特殊符號需要跳脫、在各渲染器上的行為，可參考 Markdown 跳脫字元與特殊符號。

用反引號包起來也保護不了 pipe。有些教學說 code span 內的 pipe 不需要轉義，但表格的儲存格分割發生在行內元素解析之前，所以 code span 裡面也需要反斜線轉義。

| 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/）。反斜線轉義在 code span 內也有效——同一組測試的 `a \| b` 案例在三個渲染器中都保住了，所以這裡的解法也是 \|。

常見陷阱

表格沒渲染出來或欄位錯位時，可參考 Markdown 表格語法錯誤：症狀別診斷與修正 依症狀排查。

儲存格內換行

Markdown 表格規格上儲存格內不能換行。一定要換行的話，可以直接寫 HTML 標籤 <br>，但部分平台不支援。

空儲存格

想把儲存格留空時，pipe 之間只放空白。連續寫 pipe 也沒問題，但加個空白比較容易讀。

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

欄位數不符

表頭有 3 欄但資料列只有 2 欄時，大部分解析器會把缺少的部分當成空儲存格處理。反過來資料列多出來的欄位會被截斷。欄位數對齊比較安全。

繁體字在等寬字體下的對齊問題

繁體中文（如「轉」「錯」「樣」）在等寬字體中佔用的顯示寬度通常比簡體中文略大，因為繁體字的筆畫更多、字形更寬。在等寬字體（monospace font）中，一個 CJK 字元通常佔 2 個 ASCII 字元的寬度，但繁體字的實際像素寬度可能比簡體字再寬一些。

這會影響等寬環境中表格的視覺對齊。例如在 terminal 或等寬預覽中，含有大量繁體字的欄位會顯得比其他欄位寬，導致 pipe 分隔線看起來沒有完全對齊。這不是 Markdown 語法的問題，而是字體度量的差異。如果需要在等寬環境中對齊含繁體字的內容，建議用表格語法本身（渲染後由瀏覽器或渲染器處理寬度）而不是靠空格手動對齊。

大量資料用 CSV 自動產生

5 列左右手寫就夠了，但超過 20 列的資料或欄位多的表格，手打會花很多時間。把試算表（Excel、Google Sheets 等）的資料複製成 CSV，貼到 CSV 轉 Markdown 轉換器，就不用擔心 pipe 對齊或轉義處理，一次轉完。CSV 轉 Markdown 表格的完整步驟可參考 CSV 轉 Markdown 表格：GFM 表格轉換指南；表格要放進 GitHub README 的話，從 CSV 直接產生的做法見 GitHub README 表格製作指南。產生的 Markdown 表格若要再轉成 HTML，可參考 Markdown 轉 HTML 完整指南；手上已有 HTML 想轉成 Markdown 的話，可看 HTML 轉 Markdown 指南。如果資料本身是 HTML 表格，要整張轉成 Markdown 表格，HTML 表格轉 Markdown 表格 會自動處理 pipe、換行與欄位數不符的情況。

常見問題

Markdown 表格可以沒有表頭嗎？

GFM 中表頭列是必須的。即使不需要表頭內容，也要寫一個空的表頭列和分隔列。

儲存格內可以放連結或圖片嗎？

行內 Markdown（[文字](URL) 或 ![alt](圖片URL)）在儲存格內可以使用。只是表格如果橫向太長會影響可讀性，實務上放連結就好。

可以指定表格的欄寬嗎？

Markdown 沒有指定欄寬的語法。渲染器會依內容自動調整。要精細控制的話得用 HTML 的 <table>。

總結

Markdown 表格語法很簡單，記住 pipe 和連字號就能快速建表。對齊設定、轉義等細節規則也有，但只要掌握基礎就不會遇到困難。

處理列數多的資料時，建議用 CSV 轉 Markdown 轉換器，把 CSV 貼上就能轉換，省去手打的麻煩，產生精確的 Markdown 表格。