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 或 WPS 里手动编辑

小技巧： 转换之前先在 Markdown 预览工具里看一眼。VS Code、Typora、Obsidian 这些编辑器都能立刻告诉你表格有没有写错。

---

问题 2：表格列宽在 Word 里分配不均

你看到的现象： 表格在 Markdown 编辑器里看着挺好，转到 Word 之后某一列占了 80% 的页面宽度，其他列被挤得看不清。

为什么会这样：

大部分 Markdown 转 Word 的工具会根据单元格内容长度来计算列宽。如果某个单元格塞了一大段文字或者一条很长的 URL，而其他单元格只有几个字，宽度分配就会严重失衡。Markdown 语法本身没有指定列宽的能力。

怎么修：

• 控制单元格内容长度。 长描述放到表格下方的段落里，或者用脚注
• 长链接用文字代替： 用 [链接文字](url) 而不是直接贴裸链接
• 用 MarkFlow 转换 —— 它默认会做列宽均衡处理，生成的 Word 表格比大部分工具可读性好得多

如果需要精确控制列宽，转换后在 Word（或 WPS）里调：选中表格 → 表格属性 → 列 → 设置首选宽度。

---

问题 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 里显示的是图片占位符、空白区域，或者只有 alt 文字，图片本身没有出来。

为什么会这样：

这是转换问题中被吐槽最多的，几乎都和图片路径有关：

1. 相对路径转换器解析不了 —— ![Alt](./images/photo.png) 在编辑器里能显示是因为编辑器知道文件在哪。转换器不一定知道
2. 远程链接需要认证 —— 放在 GitHub 私有仓库、Google Drive、语雀、飞书里的图片，转换时下载不了
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 完整指南 —— 端到端转换工作流