Markdown 轉換疑難排解：表格、程式碼、圖片問題全攻略

你的 Markdown 寫得好好的，預覽也沒問題，按下「轉換」——結果慘不忍睹。表格整個跑掉，程式碼變成沒有顏色的純文字，圖片不見了，LaTeX 公式變成一串看不懂的東西。

這種狀況我們看過太多次了。透過 MarkFlow 協助無數使用者將 Markdown 轉成 Word、PDF 和 HTML，我們歸納出最常見的轉換失敗情境和解決方法。以下 15 個問題都是實際案例，直接給你解法，不廢話。

問題速查表

---

表格問題

問題 1：表格欄位在 Word 裡錯位或合併

你看到的狀況： 在編輯器裡排得整整齊齊的表格，轉成 Word 之後欄位合併了、內容溢出，甚至整個表格結構直接消失。

為什麼會這樣：

最常見的原因就是表格語法寫錯了。Markdown 表格的格式要求其實蠻嚴格的，少一個 | 或分隔列的欄數對不上，整個表格就會壞掉。

常見的錯誤寫法：

<!-- 錯誤：缺少開頭的管道符 -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- 錯誤：分隔列欄數和表頭對不上 -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

怎麼修：

每列前後都加 |，欄數保持一致：

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| 靠左對齊  | 置中     | 靠右對齊   |
| Cell 1   | Cell 2   | Cell 3    |

幾個關鍵規則：

• 每列首尾都要有管道符 |
• 分隔列的欄數必須和表頭一致
• 用冒號控制對齊方式 —— :--- 靠左，:---: 置中，---: 靠右
• 不要用合併儲存格 —— 標準 Markdown 不支援。有需要的話，轉完之後在 Word 裡手動編輯

小技巧： 轉換之前先在 Markdown 預覽工具裡看一眼。VS Code、Typora、Obsidian 這些編輯器都能馬上告訴你表格有沒有寫錯。

---

問題 2：表格欄寬在 Word 裡分配不均

你看到的狀況： 表格在 Markdown 編輯器裡看起來很正常，轉到 Word 之後某一欄佔了 80% 的頁面寬度，其他欄被擠得看不清楚。

為什麼會這樣：

大部分 Markdown 轉 Word 工具會根據儲存格內容長度來計算欄寬。如果某個儲存格塞了一大段文字或一條很長的網址，而其他儲存格只有幾個字，寬度分配就會嚴重失衡。Markdown 語法本身沒辦法指定欄寬。

怎麼修：

• 控制儲存格內容長度。 長說明移到表格下方的段落裡，或用註腳
• 長網址用文字連結代替： 用 [連結文字](url) 而不是直接貼裸網址
• 用 MarkFlow 轉換 —— 它預設會做欄寬平衡處理，產出的 Word 表格比多數工具好讀很多

如果需要精確控制欄寬，轉換後在 Word 裡調整：選取表格 → 表格內容 → 欄 → 設定慣用寬度。

---

問題 3：儲存格裡的特殊字元破壞表格結構

你看到的狀況： 表格儲存格裡的管道符 | 把欄位結構搞亂了，或 HTML 實體被當成純文字顯示。

為什麼會這樣：

管道符 | 就是 Markdown 表格的欄位分隔符。儲存格內容裡出現了 |，解析器會把它當成欄位邊界。

怎麼修：

用反斜線跳脫：

| 指令 | 說明 |
|:--------|:------------|
| `echo "a \| b"` | 透過管道符過濾輸出 |
| `status: pass\|fail` | 顯示通過或失敗狀態 |

其他特殊字元的處理方式：

• 管道符用 \| 跳脫
• 如果需要 & 符號，可以用 HTML 實體 &
• 用行內程式碼反引號包住內容可以防止 Markdown 解析

---

程式碼區塊問題

問題 4：程式碼區塊轉換後語法高亮消失

你看到的狀況： 編輯器裡標記得漂漂亮亮的 Python 或 JavaScript 程式碼，到了 Word 變成黑白純文字。

為什麼會這樣：

兩個常見原因：

1. 沒寫語言識別字 —— 用了三個反引號但沒指定語言
2. 轉換工具不支援高亮 —— 很多基本款轉換器在匯出 Word/PDF 時會把語法高亮拿掉

差別在這裡：

<!-- 沒有高亮 —— 缺少語言標籤 -->
```
function hello() {
  console.log("Hello");
}
```

<!-- 有高亮 —— 指定了語言 -->
```javascript
function hello() {
  console.log("Hello");
}
```

怎麼修：

在三個反引號後面一定要寫上語言名稱。常用的語言識別字：

如果加了語言標籤還是沒有高亮，那問題出在轉換工具上。MarkFlow 在 Word 和 PDF 輸出中都保留語法高亮——程式碼會有顏色、等寬字型和正確的縮排。

---

問題 5：行內程式碼格式消失

你看到的狀況： 用單反引號包住的 config.yaml 或 npm install 在轉換後變成了普通文字，完全看不出是程式碼。

為什麼會這樣：

有些轉換器把行內程式碼當普通文字處理，不套用任何樣式。語法有辨識到，但輸出時沒給等寬字型或背景色。

怎麼修：

• 用能正確處理行內程式碼樣式的轉換器。 MarkFlow 會在 Word 輸出中幫行內程式碼加上等寬字型和淡色背景
• 避免行內程式碼裡巢狀反引號。 如果程式碼裡有反引號，用雙反引號包住：`含反引號`的程式碼` 寫成 ``含反引號`的程式碼``
• 不要把行內程式碼拿來當強調用 —— 要強調請用 粗體 或 斜體。反引號只用在真正的程式碼、指令、檔案名稱和技術識別字上

---

問題 6：程式碼縮排和空白出錯

你看到的狀況： Word 輸出的程式碼區塊縮排不對——要麼全部靠左，要麼 Tab 變成長短不一的空格。

為什麼會這樣：

Markdown 解析器和 Word 的渲染引擎對 Tab 轉空格的處理方式不同。有些轉換器還會吃掉開頭的空格，或把多個空格壓成一個。

怎麼修：

• 在 Markdown 程式碼區塊裡用空格而不是 Tab。 多數規範建議 2 或 4 個空格。Tab 在不同轉換器裡的表現不一致
• 用圍籬式程式碼區塊（三個反引號）而不是縮排式程式碼區塊（4 個空格縮排）。圍籬式的解析更可靠：

<!-- 建議：圍籬式程式碼區塊 -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- 避免：縮排式程式碼區塊（4 個空格） -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• 轉換完馬上檢查輸出。 如果空白有問題，代表是轉換器的問題，不是你 Markdown 寫錯了。換個工具試試或回報 bug

---

圖片問題

問題 7：圖片轉換後不顯示

你看到的狀況： 轉出來的 Word 或 PDF 裡顯示的是破圖圖示、空白區域，或者只有替代文字，圖片本身沒出來。

為什麼會這樣：

這是轉換問題中被抱怨最多的，幾乎都跟圖片路徑有關：

1. 相對路徑轉換器解析不了 —— ![Alt](./images/photo.png) 在編輯器裡能顯示是因為編輯器知道檔案在哪。轉換器不一定知道
2. 遠端連結需要驗證 —— 放在 GitHub 私有 repo、Google Drive 或 Notion 裡的圖片，轉換時下載不了
3. 協定問題 —— 有些轉換器不處理 file:// 路徑或本機絕對路徑
4. 格式不支援 —— 某些轉換器處理不了 SVG、WebP 或 TIFF

怎麼修：

最穩當的做法是用公開可存取的圖片 URL：

<!-- 最可靠：絕對 URL -->
![架構圖](https://your-domain.com/images/diagram.png)

<!-- 也可靠：base64 嵌入（適合小圖） -->
![圖示](data:image/png;base64,iVBORw0KGgo...)

用 MarkFlow： 直接把 .md 檔案和圖片資料夾一起拖進去——相對路徑會自動解析。也可以貼上帶圖片 URL 的 Markdown，圖片會自動嵌入 Word 輸出。

---

問題 8：圖片在 Word 裡大小不對

你看到的狀況： 在 Markdown 預覽裡大小剛好的圖片，轉到 Word 裡要麼小到看不清，要麼大到把版面撐爆。

為什麼會這樣：

Markdown 原生語法不支援指定圖片尺寸。![alt](url) 格式沒有寬高參數。大多數轉換器會按圖片原始像素尺寸插入，這可能跟 Word 頁面寬度完全不搭。

怎麼修：

部分 Markdown 方言支援透過 HTML 控制圖片尺寸：

<!-- 用 HTML 控制圖片大小 -->
<img src="./diagram.png" alt="系統架構圖" width="600" />

但不是所有 Markdown 轉 Word 工具都處理 HTML 標籤。你可以：

• 在加到 Markdown 之前先調整原始圖片尺寸 —— 寬度控制在 600-800px 左右，適合大部分 Word 頁面版面
• 用 HTML img 標籤加 width 屬性（如果你的轉換器支援行內 HTML）
• 轉換後在 Word 裡調整 —— 對圖片按右鍵 → 大小及位置 → 設定寬度

Word 輸出建議的圖片尺寸：

• 全寬圖片：600-800px 寬
• 行內示意圖：400-500px 寬
• 圖示或徽章：100-200px 寬

---

問題 9：Base64 嵌入的圖片轉換失敗

你看到的狀況： 用 base64 data URI 嵌入的圖片在預覽裡正常，但轉出來的文件裡圖片壞了或直接被移除了。

為什麼會這樣：

Base64 編碼會讓檔案大小增加約 33%。有些轉換器對 data URI 有大小限制，或者乾脆不解析 data:image/...;base64,... 這種格式。

怎麼修：

• Base64 圖片要小 —— 編碼後 100KB 以下（原檔約 75KB）。圖示和小 logo 沒問題，截圖和照片就別用 base64 了
• 大圖用實際圖片檔案。 放到伺服器上或跟 .md 檔案放在一起
• 查一下你的轉換器是否支援 data URI。 MarkFlow 在 Word 和 PDF 輸出中都支援 base64 圖片，但單張圖片有大約 2MB 的實際上限

---

LaTeX 數學公式和 Mermaid 流程圖問題

問題 10：LaTeX 公式變成純文字

你看到的狀況： Word 文件裡沒有渲染好的公式，而是直接顯示了 LaTeX 原始碼：$E = mc^2$ 或 $$\int_{0}^{1} x^2 dx$$ 原封不動出現在文件裡。

為什麼會這樣：

LaTeX 數學公式不是標準 Markdown 或 GFM 的一部分。它是一個擴充功能，需要特定的渲染引擎（KaTeX 或 MathJax）。大部分基礎轉換器——包括沒加參數的 Pandoc、沒裝擴充套件的 VS Code、Dillinger——都不處理 LaTeX 語法。

怎麼修：

先確認語法沒寫錯：

<!-- 行內公式：單錢號 -->
公式 $E = mc^2$ 描述了質能等價關係。

<!-- 區塊公式：雙錢號 -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

然後用支援 LaTeX 的轉換器：

常見的 LaTeX 寫錯導致渲染失敗：

<!-- 錯誤：開頭的 $ 後面有空格 -->
$ E = mc^2 $

<!-- 正確：$ 後面緊接內容 -->
$E = mc^2$

<!-- 錯誤：缺少結尾的分隔符 -->
$$\int_{0}^{1} x^2 dx

<!-- 正確：前後分隔符成對 -->
$$\int_{0}^{1} x^2 dx$$

---

問題 11：Mermaid 流程圖在輸出中不顯示

你看到的狀況： 轉出來的 Word/PDF 裡沒有流程圖或序列圖，而是把 Mermaid 原始碼當成普通程式碼區塊顯示了。

為什麼會這樣：

Mermaid 是基於 JavaScript 的渲染引擎，需要瀏覽器或 Node.js 環境來產生圖形。大多數 Markdown 轉 Word 工具只做文字處理，不執行 JavaScript，所以 Mermaid 程式碼區塊被當成普通程式碼。

怎麼修：

先確認 Mermaid 語法沒問題：

```mermaid
graph TD
    A[開始] --> B{判斷條件}
    B -->|是| C[動作 1]
    B -->|否| D[動作 2]
    C --> E[結束]
    D --> E
```

支援 Mermaid 渲染到 Word/PDF 的工具：

• MarkFlow —— 把 Mermaid 圖渲染成圖片嵌入 Word
• Typora —— 預覽中渲染 Mermaid，可匯出 PDF
• Pandoc —— 需要安裝 mermaid-filter 外掛（npm install -g mermaid-filter）

不支援 Mermaid 的轉換器的替代做法：

1. 用 Mermaid Live Editor 渲染你的圖
2. 匯出為 PNG 或 SVG
3. 把 Markdown 裡的 Mermaid 程式碼區塊替換成圖片參考
4. 正常轉換

多了一個手動步驟，但能保證圖在任何轉換器裡都能正常顯示。

---

格式與結構問題

問題 12：Word 輸出的標題層級不對

你看到的狀況： Word 裡的標題層級跟 Markdown 裡寫的不一樣。H2 變成了 H1，或所有標題大小都一樣。

為什麼會這樣：

兩個常見原因：

1. Markdown 裡寫了多個 H1。 一份文件應該只有一個 H1（就是標題）。有些轉換器偵測到多個 H1 時會自動重排或合併標題層級
2. 轉換器對 Markdown 標題到 Word 樣式的對應方式不同。 有些工具會把第一個標題當文件標題，不管它是幾級標題

怎麼修：

遵循正確的標題層級：

# 文件標題（H1 —— 只用一次）

## 章節標題（H2 —— 主要分節）

### 小節標題（H3 —— 章節內部）

#### 細節標題（H4 —— 很少需要）

• 不要跳級 —— 別從 H2 直接跳到 H4
• H1 只在文件開頭用一次，或讓轉換器從 frontmatter 的 title 欄位自動產生
• 在 Word 裡檢查樣式面板 —— 標題應該顯示為「標題 1」「標題 2」等。如果顯示為「內文」，代表轉換器沒正確對應

---

問題 13：巢狀列表縮排遺失

你看到的狀況： 精心縮排的多層列表在 Word 裡被壓平了——所有項目都在同一層。

為什麼會這樣：

縮排不一致是主要原因。Markdown 需要統一的縮排空格數才能辨識巢狀層級。Tab 和空格混用，或一下 2 個空格一下 3 個空格，解析器就會搞混。

怎麼修：

每一層巢狀統一用 4 個空格（或 1 個 Tab），保持一致：

- 第一層
    - 第二層
        - 第三層
    - 回到第二層
- 回到第一層

1. 第一項
    1. 子項一
    2. 子項二
2. 第二項
    - 數字列表下面混用無序列表

常見錯誤：

<!-- 錯誤：縮排不一致（2 個空格接著 3 個） -->
- 項目 A
  - 子項 A（2 個空格）
   - 子項 B（3 個空格 —— 解析器搞混了）

<!-- 正確：統一 4 個空格 -->
- 項目 A
    - 子項 A
    - 子項 B

如果統一了縮排還是被壓平，試試換個轉換工具。MarkFlow 在 Word 輸出中保留巢狀列表縮排，包含有序和無序列表混用的情況。

---

問題 14：註腳消失或顯示異常

你看到的狀況： 註腳參考 [^1] 在轉出來的文件裡變成了純文字，底部的註腳內容也不見了或變成普通段落。

為什麼會這樣：

註腳是 GFM 的擴充功能，不屬於原始 Markdown 規格。只支援基礎 Markdown 的轉換器不會處理註腳語法。

怎麼修：

正確的註腳語法：

這個觀點需要引用來源[^1]。這裡是另一個重點[^note]。

[^1]: 王大明. (2025). 《論文標題》. 期刊名稱.
[^note]: 這是一條較長的註腳，包含多個句子。
    接續行需要縮排 4 個空格。

確認以下幾點：

• 參考 [^id] 和定義 [^id]: 使用相同的識別字
• 註腳定義放在文件末尾（至少在所有參考之後）
• 你的轉換器支援 GFM 註腳 —— MarkFlow、Pandoc、Typora 都能正確處理

---

問題 15：Emoji 顯示為空白方框

你看到的狀況： 勾勾、火箭、警告等 Emoji 在 Word 輸出裡變成了空白方框或問號。

為什麼會這樣：

Word 文件使用的字型不包含 Emoji 字形。轉換器把 Markdown 文字對應到 Word 時，會套用 Calibri 或新細明體之類的標準字型，這些字型可能沒有 Unicode Emoji 字元。

怎麼修：

• 轉換後： 在 Word 裡選取 Emoji 字元，把字型改成 "Segoe UI Emoji"（Windows）或 "Apple Color Emoji"（macOS）
• 轉換前： 如果 Emoji 很重要，考慮用文字替代或用圖片代替
• 用支援 Emoji 字型的轉換器： MarkFlow 會在 Word 輸出中把 Emoji 對應到合適的系統字型

---

預防：怎麼從源頭避免轉換問題

大部分轉換問題是可以預防的。把下面這些習慣融入你寫 Markdown 的日常工作流程。

轉換前先跑一遍檢查

用 Markdown linter 在轉換之前抓出語法問題：

# 安裝 markdownlint CLI
npm install -g markdownlint-cli

# 檢查你的檔案
markdownlint document.md

VS Code 使用者：裝一個 "markdownlint" 擴充套件，寫的時候就能即時檢查。

用跟輸出一致的預覽

編輯器預覽和轉換器輸出用的是不同的渲染引擎。VS Code 裡看起來沒問題的東西到了 Word 裡可能就壞了。正式匯出之前一定先做一次測試轉換。

統一你的 Markdown 寫法

訂好規範，持續遵守：

• 縮排： 巢狀統一用 4 個空格
• 換行： 區塊元素之間空一行
• 程式碼區塊： 全部用圍籬式（不用縮排式），一定要有語言標籤
• 圖片： 路徑格式統一（全部相對路徑或全部絕對路徑）
• 表格： 每列首尾都有管道符

如果你對 Markdown 規範還不太熟，我們的 Markdown 基礎語法指南 詳細介紹了每個元素。註腳、任務清單等進階功能請看 擴充語法指南。

維護一份測試文件

準備一個 Markdown 檔案，把你用到的每種元素都寫一個進去——表格、程式碼區塊、數學公式、流程圖、巢狀列表、註腳、Emoji。每次換工具或升級版本的時候跑一遍轉換，能在影響正式文件之前發現問題。

---

什麼情境用什麼轉換器

不同的工具擅長處理不同類型的問題：

---

常見問題

問：為什麼我的 Markdown 表格轉 Word 後會壞掉？ 答：最常見的原因是管道符語法不一致——缺少首尾管道符，或分隔列欄數跟表頭對不上。轉換之前先在 Markdown 預覽裡驗證表格語法。

問：轉 Word 時怎麼保留程式碼區塊的語法高亮？ 答：三個反引號後面一定要寫上語言名稱（例如 ```python）。然後用 MarkFlow 這樣能在 Word 輸出中保留高亮的轉換器。

問：為什麼 Markdown 轉 Word 後圖片不見了？ 答：轉換器解析不了你的圖片路徑。遠端圖片用絕對 URL，或用 MarkFlow 這樣的工具，把 .md 檔案和圖片資料夾一起上傳，相對路徑就能自動解析了。

問：LaTeX 數學公式能不丟格式地轉成 Word 嗎？ 答：可以，但你需要支援 LaTeX 的轉換器。MarkFlow、Pandoc（加數學參數）和 Typora 都能正確渲染 LaTeX。基礎轉換器會把 LaTeX 原始碼當純文字輸出。

問：為什麼 Mermaid 流程圖在轉換後變成了程式碼？ 答：大部分轉換器不執行 JavaScript，而 Mermaid 需要 JavaScript 環境。用 MarkFlow 可以自動渲染 Mermaid，或先用 Mermaid Live Editor 把圖匯出為圖片。

問：怎麼修復巢狀列表在 Word 裡縮排遺失的問題？ 答：在 Markdown 裡每層巢狀嚴格用 4 個空格。不要混用 Tab 和空格。如果問題還在，換個轉換器試試——不同工具對巢狀列表的支援程度不同。

---

相關資源

• Markdown 轉 Word 轉換器 —— 支援完整格式的轉換
• Markdown 轉 PDF 轉換器 —— 產生可列印的 PDF
• Markdown 轉 HTML 轉換器 —— 匯出乾淨的語意化 HTML
• Markdown 基礎語法指南 —— 掌握基礎語法
• Markdown 擴充語法指南 —— 進階功能和 GFM 擴充
• Markdown 轉 Word 完整指南 —— 端到端轉換工作流程