企业官网建设流程全解析

AI 生成的内容，落到 Word 里就"毁容"——这事我踩过的坑能写满一页纸。你让模型输出一份带流程图的方案，聊天窗口里看着漂漂亮亮，复制到 Word 里，Mermaid 代码变成一堆裸文本，LaTeX 公式变成\frac{a}{b}这种天书，表格列宽拖不动，代码块缩进全乱。更气人的是，明明内容是对的，交付出去却像半成品。这篇就聊一套我自己跑了大半年的工作流：把 AI 生成的 Markdown（含 Mermaid 图表、LaTeX 公式）无损转成 Word 文档，公式是真公式、图表是真图、排版能直接交差。适合经常用 AI 写技术文档、方案书、论文初稿，又必须交付 Word 格式的人——不管你是刚接触 Pandoc 的新手，还是已经被"公式图片转 Word"折磨过的老手，都能从里面抄到能直接用的配置和命令。

1. 先搞清楚：为什么复制粘贴一定会翻车

1.1 剪贴板只认"纯文本"和"富文本"，不认语义

大多数人转 Word 的第一反应是 Ctrl+C、Ctrl+V。这个动作的本质，是把渲染后的视觉结果塞进剪贴板。问题在于，剪贴板里能承载的格式只有两类：纯文本（Plain Text）和富文本（RTF/HTML 片段）。Markdown 的语义——"这是一个二级标题""这是一个公式""这是一个流程图"——在复制的那一刻就已经丢了。

举个具体的例子。AI 输出这样一段：

## 2. 数据流设计 系统吞吐量满足 $Q = \frac{C}{T}$ 的约束。 ```mermaid graph LR A[采集] --> B[清洗] --> C[入库]

你在预览器里看到的是：一个加粗标题、一个漂亮的分数公式、一张横向流程图。但复制到 Word 里，公式变成 `$Q = \frac{C}{T}$` 这串字符，Mermaid 变成一段带箭头的代码。Word 根本不知道 `\frac` 是什么意思，它只看到反斜杠和字母。 > 提示：判断一个转换方案靠不靠谱，就看它处理的是"渲染结果"还是"源语义"。前者必然丢信息，后者才能无损。 ### 1.2 Word 的公式、图表、表格是三套独立体系 要理解为什么难，得知道 Word 内部是怎么存这些东西的。 - **公式**：Word 从 2007 版开始用 OMML（Office Math Markup Language）存公式，这是一种 XML 方言。而 LaTeX 是另一套完全不同的数学标记语言。两者之间需要"翻译"，不是简单替换字符。 - **图表**：Word 本身没有"流程图"这种原生对象，要么是嵌入的图片（PNG/SVG），要么是用形状（Shape）拼出来的矢量图。Mermaid 是文本描述，必须先渲染成图。 - **表格**：Word 表格有列宽、合并单元格、边框样式等属性，Markdown 表格只有 `|` 分隔的纯文本，列宽信息压根不存在。 所以"无损转换"的本质，是找到一条能把 Markdown 语义分别映射到 Word 三套体系的路径。这也是为什么单纯复制粘贴永远做不到——它只走了一条通道。 ### 1.3 三条主流路线的取舍 我实测过三条路线，各有适用场景，先给结论再展开。 | 路线 | 核心工具 | 公式处理 | Mermaid 处理 | 适合场景 | |------|---------|---------|-------------|---------| | 纯 Pandoc | Pandoc + LaTeX 引擎 | 原生 OMML，无损 | 需预处理成图片 | 公式多、图表少的学术文档 | | Pandoc + 过滤器 | Pandoc + mermaid-filter | 原生 OMML | 自动渲染嵌入 | 图表公式都多的技术方案 | | 在线转换 | 各类网页工具 | 常转成图片 | 常转成图片 | 应急、对可编辑性无要求 | 关键差异在公式：**转成图片的公式，在 Word 里不能编辑、不能搜索、缩放会糊**。如果你交付的文档对方要改公式，图片方案直接出局。所以只要条件允许，我都优先选 Pandoc 路线，让公式以原生 OMML 落地。 ## 2. 环境搭建：Pandoc 和 LaTeX 引擎怎么配才不踩坑 ### 2.1 Pandoc 安装：版本和路径两个坑 Pandoc 是这套工作流的核心，它负责把 Markdown 解析成 AST（抽象语法树），再输出成 docx。安装本身不难，但有两个坑我踩过。 第一个是**版本**。热词里有人搜"pandoc v2.0"，我要提醒一句：2.0 太老了，对 Mermaid 和较新 Markdown 语法的支持都不好。建议直接用 3.x 版本，目前稳定版在 3.1 以上。Windows 用户去官网下 `.msi` 安装包，一路下一步即可；macOS 用 `brew install pandoc`；Linux 用包管理器或直接下二进制。 第二个是**PATH 环境变量**。Windows 下如果安装时没勾选"Add to PATH"，命令行里敲 `pandoc` 会提示找不到命令。验证方法很简单： ```bash pandoc --version

能打印出版本号就说明配好了。打印不出来，要么重装勾选 PATH，要么手动把安装目录加进环境变量。

2.2 LaTeX 引擎：公式转换的幕后功臣

很多人不知道，Pandoc 转 docx 时，公式能变成原生 OMML，靠的其实是它内置的 texmath 库，并不需要完整安装 LaTeX。但如果你要转 PDF，或者某些复杂公式 texmath 处理不了，就需要一个真正的 LaTeX 引擎兜底。

热词里"latex安装教程""latex下载"搜索量很高，说明这是普遍痛点。我的建议是：只转 Word 的话，先别装完整 LaTeX，它动辄几个 G，装完还容易和系统里的其他工具冲突。等真的遇到 texmath 搞不定的公式，再装一个轻量引擎。

真要装，选这两个之一：

• MiKTeX（Windows 友好）：按需下载宏包，初次安装体积小，遇到缺包会自动提示安装。
• TeX Live（跨平台全量）：一次装全，体积大但省心，适合长期重度使用。

装完后验证：

xelatex --version

有版本输出即可。这里选 XeLaTeX 而不是 pdfLaTeX，是因为它对中文和字体的支持更好，后面转 PDF 会用到。

2.3 Mermaid 渲染：两条路，选适合你的

Mermaid 要变成 Word 里的图，必须先渲染成图片。有两条路：

路线 A：mermaid-filter（Pandoc 过滤器）

这是最省事的方式。装好 Node.js 后：

npm install -g mermaid-filter

然后转换时加--filter mermaid-filter，Pandoc 遇到```mermaid代码块会自动调用它渲染成 PNG 并嵌入。优点是全自动，缺点是依赖 Node 环境，且渲染质量受默认配置限制。

路线 B：Mermaid CLI 手动渲染

npm install -g @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b white -s 3

-b white指定白底，-s 3是 3 倍缩放（保证清晰度）。手动渲染的好处是可控——你可以调主题、调尺寸、调背景色。热词里有人问"mermaid 编辑器中设置所有节点为白底黑字的语句"，其实就是主题配置问题，在 CLI 里可以用配置文件搞定。

我个人的选择是：图表少用路线 A，图表多用路线 B 批量渲染。因为批量渲染可以统一风格，避免每张图配色不一致。

3. 公式无损：LaTeX 到 Word 原生 OMML 的完整链路

3.1 为什么公式是重灾区

公式转换是整条链路里最容易出问题的一环。原因在于 LaTeX 和 OMML 的表达能力并不完全对等。

LaTeX 里一个简单的\frac{a}{b}，对应 OMML 里的结构是：

<m:f> <m:num><m:r><m:t>a</m:t></m:r></m:num> <m:den><m:r><m:t>b</m:t></m:r></m:den> </m:f>

Pandoc 的 texmath 库负责做这个映射。大部分常见符号（分数、上下标、求和、积分、矩阵）它都能处理，但一些冷门宏包、自定义命令、复杂排版（比如align环境的某些用法）就可能翻车。

3.2 行内公式和行间公式的写法规范

要让转换顺利，源 Markdown 里的公式写法得规范。这是很多人忽略的一点。

行内公式用单个美元符号：

当 $x > 0$ 时，函数单调递增。

行间公式用双美元符号，且前后要空行：

系统满足如下约束： $$ \int_{0}^{T} f(t) \, dt = C $$

注意：行间公式前后不空行，Pandoc 有时会把它当成行内公式处理，导致排版错乱。这个坑我在处理一份 50 页的方案时踩过，排查了半天才发现是空行问题。

3.3 实测：哪些公式能无损，哪些会翻车

我拿一批常见公式做了实测，结果如下：

结论很清楚：标准 LaTeX 数学语法基本都能无损，自定义命令和宏包扩展容易翻车。所以让 AI 生成公式时，最好在提示词里明确"只用标准 LaTeX 数学语法，不要自定义命令"。

3.4 公式转图片的兜底方案

万一遇到 texmath 处理不了的公式，还有个兜底方案：把公式渲染成图片再嵌入。用latex.codecogs.com这类在线渲染服务，或者本地用 LaTeX 引擎渲染。

但我要强调：这是下策。图片公式在 Word 里不能编辑、不能搜索、打印放大后会糊。热词里"公式图片转 word"搜索量高，说明很多人被迫走了这条路，但如果你能控制源文档，还是尽量让公式以原生形式落地。

4. Mermaid 图表：从代码块到 Word 内嵌图的转换细节

4.1 Mermaid 代码块的识别与预处理

Pandoc 默认不认识```mermaid这个语言标记，它会当成普通代码块处理，输出成等宽字体的文本。要让它变成图，必须经过预处理或过滤器。

用 mermaid-filter 时，Pandoc 的调用方式：

pandoc input.md -o output.docx --filter mermaid-filter

过滤器会扫描 AST，找到语言标记为mermaid的代码块，调用 Mermaid CLI 渲染成图片，替换原来的代码块节点。

手动预处理的话，思路是先把所有 Mermaid 代码块抽出来单独渲染，再在 Markdown 里替换成图片引用：

![流程图](diagrams/flow-01.png)

4.2 渲染质量：分辨率和背景色两个关键参数

Mermaid 默认渲染出来的图，分辨率往往不够，插到 Word 里放大就糊。解决办法是提高缩放倍数。

用 mermaid-cli 时：

mmdc -i flow.mmd -o flow.png -s 3 -b white

-s 3表示 3 倍缩放，一般文档用 2 到 3 倍就够，打印级文档可以到 4 倍。-b white指定白色背景——这点很重要，默认背景可能是透明的，插到 Word 里如果页面有底色，图会显得脏。

热词里"mermaid 编辑器中设置所有节点为白底黑字的语句"其实问的是主题配置。在 CLI 里可以通过配置文件统一设置：

{ "theme": "base", "themeVariables": { "primaryColor": "#ffffff", "primaryTextColor": "#000000", "primaryBorderColor": "#333333", "lineColor": "#333333" } }

然后mmdc -c config.json -i flow.mmd -o flow.png。这样所有节点都是白底黑字，风格统一。

4.3 图表尺寸与 Word 页面宽度的匹配

Mermaid 渲染出来的图，宽度可能超过 Word 页面可用宽度（A4 纸去掉页边距大约 16cm）。图太宽会被 Word 自动缩放，导致字变小。

我的做法是：渲染时控制输出宽度，或者在 Markdown 里用 Pandoc 的属性指定尺寸：

![流程图](flow.png){ width=15cm }

Pandoc 会把这个宽度属性写进 docx 的图片 XML 里。这样图就不会溢出页面。

4.4 复杂图表的拆分策略

一张图塞太多节点，插到 Word 里必然看不清。我的经验是：单张流程图节点控制在 15 个以内，超过就拆。

比如一个完整的系统架构，可以拆成"数据采集层""处理层""存储层"三张图，每张图聚焦一个层次。这样既清晰，又方便在文档里分节讲解。热词里"mermaid 格式拓扑图生成""mermaid 瀑布图"这类需求，往往图会比较复杂，拆分策略尤其重要。

5. 表格、代码块、换行：那些不起眼但天天出问题的地方

5.1 Markdown 表格转 Word 后的列宽问题

Markdown 表格转成 Word 表格后，最常见的问题是列宽无法拖动。热词里"word 表格列宽无法拖动"就是这个。

原因通常是 Pandoc 生成的表格用了固定布局（fixed layout），且没有指定列宽。解决办法有两个：

一是用 Pandoc 的--columns参数控制表格总宽度，让各列按内容比例分配：

pandoc input.md -o output.docx --columns=100

二是在 Markdown 里用网格表格（grid table）显式指定列宽：

+--------+------------------+ | 字段 | 说明 | +========+==================+ | id | 主键，自增 | +--------+------------------+

网格表格的列宽由+---+的横线长度决定，Pandoc 会把这个比例写进 Word。

5.2 代码块的语法高亮与字体

Pandoc 转 docx 时，代码块默认用等宽字体，但不会带语法高亮（除非用--highlight-style配合特定输出格式）。Word 里想要高亮，得靠样式表。

我的做法是：转 docx 时用--reference-doc指定一个模板文档，模板里定义好代码块的样式（字体、背景色、边框）。这样所有代码块自动套用统一样式。

pandoc input.md -o output.docx --reference-doc=template.docx

模板文档的制作方法：先随便转一个 docx，打开后修改"Source Code"样式的字体和背景，另存为模板。

5.3 Markdown 换行在 Word 里的表现差异

Markdown 里单个换行（行尾不加两个空格）在渲染时通常被当成空格，不产生新行。但 Word 里你可能希望它真的换行。

Pandoc 有个参数控制这个行为：

pandoc input.md -o output.docx --wrap=preserve

--wrap=preserve会保留源文件里的换行。不过要注意，这可能导致段落内出现意外的换行。我的建议是：源 Markdown 里该用空行分段就用空行，别依赖单换行，这样转换结果最可控。

5.4 图片路径与相对引用

Markdown 里的图片路径，Pandoc 转换时是相对于当前工作目录解析的，不是相对于 Markdown 文件所在目录。这是个经典坑。

比如你的文件结构是：

project/ docs/ report.md images/ flow.png

在project/目录下执行pandoc docs/report.md，Markdown 里写![](../images/flow.png)是对的。但如果你cd docs再执行，路径就得改成![](../images/flow.png)依然对，但如果你写的是![](images/flow.png)就找不到。

最稳的做法是：统一在项目根目录执行 Pandoc，图片路径用相对于根目录的路径。

6. 一套可复用的完整工作流

6.1 目录结构与命名约定

我把这套流程固化成了一个目录结构，每次新文档直接套：

doc-project/ src/ main.md # 主文档 chapters/ # 分章节 diagrams/ flow-01.mmd # Mermaid 源文件 flow-01.png # 渲染后的图 assets/ template.docx # Word 模板 mermaid-config.json build.sh # 一键构建脚本 output/ result.docx

命名约定：图表源文件和渲染图同名，只改扩展名，方便对应。

6.2 一键构建脚本

把整个流程写成一个脚本，避免每次手敲命令：

#!/bin/bash set -e # 1. 渲染所有 Mermaid 图 for f in diagrams/*.mmd; do name=$(basename "$f" .mmd) mmdc -c assets/mermaid-config.json -i "$f" -o "diagrams/$name.png" -s 3 -b white done # 2. 转换 Markdown 到 Word pandoc src/main.md \ -o output/result.docx \ --reference-doc=assets/template.docx \ --filter mermaid-filter \ --columns=100 \ --wrap=preserve \ --toc \ --number-sections echo "构建完成：output/result.docx"

--toc生成目录，--number-sections自动给章节编号。这两个参数对长文档特别有用。

6.3 转换后的验收清单

转完不能直接交，我一般过一遍这个清单：

• 公式是否可编辑（双击公式看是否进入公式编辑器）
• Mermaid 图是否清晰（放大到 200% 看是否糊）
• 表格列宽是否能拖动
• 代码块样式是否统一
• 目录页码是否正确
• 图片是否溢出页面

任何一项不过关，回到对应章节排查。

7. 踩坑实录：几个让我加班到深夜的问题

7.1 关闭 Word 时卡顿：不是文档的错

热词里"关闭 word 时卡顿""word 关闭时卡顿"搜索量不低。我遇到过，一开始以为是文档太大，后来发现是加载项冲突。

排查方法：Word 里进"文件 - 选项 - 加载项"，把 COM 加载项全部禁用，再关闭试试。如果流畅了，逐个启用定位问题加载项。常见元凶是某些 PDF 插件、翻译插件、公式插件（比如 MathType 的某些版本）。

顺带说一句，热词里"mathtype 如何嵌入到 word 中"也是个高频问题。MathType 装完后如果 Word 里看不到选项卡，通常是加载项没启用，或者版本不匹配（32 位 Word 配 64 位 MathType 就会出问题）。

7.2 公式编号对不齐：align 环境的坑

用align环境写多行公式时，Pandoc 转出来的编号经常对不齐。原因是 OMML 对 align 的支持不完整。

我的绕法：放弃 align，改用单独的公式块，编号手动写在公式右侧。虽然土，但结果可控。

$$ Q = \frac{C}{T} \quad (1) $$

7.3 中文字体在转换后变成宋体

Pandoc 转 docx 时，如果没有指定字体，中文默认可能变成宋体，和你模板里的字体不一致。解决办法是在reference-doc模板里把"正文"样式的字体设成你要的（比如微软雅黑），并确保中文字体也设置了。

7.4 图片在 Word 里显示为红叉

这个通常是图片路径问题，或者图片格式不被支持。Pandoc 支持 PNG、JPEG、GIF、SVG（部分）。如果用了 SVG，某些 Word 版本不支持，会显示红叉。统一用 PNG 最稳。

8. 进阶：让 AI 直接输出"可转换友好"的 Markdown

8.1 提示词里要约束的几件事

与其转完再修，不如让 AI 一开始就输出规范格式。我在提示词里会加这几条约束：

• 公式只用标准 LaTeX 数学语法，不用自定义命令
• Mermaid 图节点不超过 15 个，复杂逻辑拆多张图
• 表格用标准 Markdown 表格语法
• 代码块标注语言类型
• 章节标题用##和###，不跳级

这样出来的 Markdown，转换成功率能提高一大截。

8.2 用 Coze 等工作流平台批量处理

热词里"markdown 转 word 工作流 coze"说明有人在做自动化。思路是把"AI 生成 - 格式校验 - Pandoc 转换"串成一条流水线。我试过类似的方案，核心是把 Pandoc 封装成一个服务，接收 Markdown 返回 docx。

不过要提醒：自动化流水线适合批量、格式统一的场景。如果每篇文档都有特殊排版要求，人工介入反而更快。

8.3 版本管理：Markdown 源文件才是真相

最后说个理念问题。这套工作流里，Markdown 源文件是唯一真相，Word 只是产物。所以源文件一定要用 Git 管理，每次改动都有记录。Word 文档随时可以从源文件重新生成，不用担心改乱。

我现在所有技术文档都是这个模式：Markdown 写、Git 管、Pandoc 转。交付 Word，存档 Markdown。改需求时改源文件重新转，比在 Word 里手动调格式快十倍。

这套流程跑下来，最深的体会是：转换的难点从来不在工具，而在源文档的规范性。源 Markdown 写得越标准，转换越顺。反过来，如果源文件里全是自定义命令、不规范表格、乱七八糟的换行，再好的工具也救不回来。所以与其花时间研究各种转换技巧，不如先把 Markdown 写作规范立起来——这是我这大半年最大的收获。