AI 生成的内容落到 Word 里就毁容——这事我踩过的坑能写满一页纸。你让模型输出一份带流程图的方案聊天窗口里看着漂漂亮亮复制到 Word 里Mermaid 代码变成一堆裸文本LaTeX 公式变成\frac{a}{b}这种天书表格列宽拖不动代码块缩进全乱。更气人的是明明内容是对的交付出去却像半成品。这篇就聊一套我自己跑了大半年的工作流把 AI 生成的 Markdown含 Mermaid 图表、LaTeX 公式无损转成 Word 文档公式是真公式、图表是真图、排版能直接交差。适合经常用 AI 写技术文档、方案书、论文初稿又必须交付 Word 格式的人——不管你是刚接触 Pandoc 的新手还是已经被公式图片转 Word折磨过的老手都能从里面抄到能直接用的配置和命令。1. 先搞清楚为什么复制粘贴一定会翻车1.1 剪贴板只认纯文本和富文本不认语义大多数人转 Word 的第一反应是 CtrlC、CtrlV。这个动作的本质是把渲染后的视觉结果塞进剪贴板。问题在于剪贴板里能承载的格式只有两类纯文本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 版开始用 OMMLOffice 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 pandocLinux 用包管理器或直接下二进制。 第二个是**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 搞不定的公式再装一个轻量引擎。真要装选这两个之一MiKTeXWindows 友好按需下载宏包初次安装体积小遇到缺包会自动提示安装。TeX Live跨平台全量一次装全体积大但省心适合长期重度使用。装完后验证xelatex --version有版本输出即可。这里选 XeLaTeX 而不是 pdfLaTeX是因为它对中文和字体的支持更好后面转 PDF 会用到。2.3 Mermaid 渲染两条路选适合你的Mermaid 要变成 Word 里的图必须先渲染成图片。有两条路路线 Amermaid-filterPandoc 过滤器这是最省事的方式。装好 Node.js 后npm install -g mermaid-filter然后转换时加--filter mermaid-filterPandoc 遇到mermaid代码块会自动调用它渲染成 PNG 并嵌入。优点是全自动缺点是依赖 Node 环境且渲染质量受默认配置限制。路线 BMermaid 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:numm:rm:ta/m:t/m:r/m:num m:denm:rm:tb/m:t/m:r/m:den /m:fPandoc 的 texmath 库负责做这个映射。大部分常见符号分数、上下标、求和、积分、矩阵它都能处理但一些冷门宏包、自定义命令、复杂排版比如align环境的某些用法就可能翻车。3.2 行内公式和行间公式的写法规范要让转换顺利源 Markdown 里的公式写法得规范。这是很多人忽略的一点。行内公式用单个美元符号当 $x 0$ 时函数单调递增。行间公式用双美元符号且前后要空行系统满足如下约束 $$ \int_{0}^{T} f(t) \, dt C $$注意行间公式前后不空行Pandoc 有时会把它当成行内公式处理导致排版错乱。这个坑我在处理一份 50 页的方案时踩过排查了半天才发现是空行问题。3.3 实测哪些公式能无损哪些会翻车我拿一批常见公式做了实测结果如下公式类型LaTeX 示例转换结果分数\frac{a}{b}无损原生 OMML上下标x^{2}_{i}无损求和积分\sum_{i1}^{n}无损希腊字母\alpha \beta \gamma无损矩阵\begin{matrix}...\end{matrix}无损分段函数\begin{cases}...\end{cases}无损自定义宏\mycmd{x}翻车显示为原文复杂 align多行对齐部分翻车结论很清楚标准 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 里替换成图片引用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 的属性指定尺寸{ width15cm }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 --columns100二是在 Markdown 里用网格表格grid table显式指定列宽-------------------------- | 字段 | 说明 | | id | 主键自增 | --------------------------网格表格的列宽由---的横线长度决定Pandoc 会把这个比例写进 Word。5.2 代码块的语法高亮与字体Pandoc 转 docx 时代码块默认用等宽字体但不会带语法高亮除非用--highlight-style配合特定输出格式。Word 里想要高亮得靠样式表。我的做法是转 docx 时用--reference-doc指定一个模板文档模板里定义好代码块的样式字体、背景色、边框。这样所有代码块自动套用统一样式。pandoc input.md -o output.docx --reference-doctemplate.docx模板文档的制作方法先随便转一个 docx打开后修改Source Code样式的字体和背景另存为模板。5.3 Markdown 换行在 Word 里的表现差异Markdown 里单个换行行尾不加两个空格在渲染时通常被当成空格不产生新行。但 Word 里你可能希望它真的换行。Pandoc 有个参数控制这个行为pandoc input.md -o output.docx --wrappreserve--wrappreserve会保留源文件里的换行。不过要注意这可能导致段落内出现意外的换行。我的建议是源 Markdown 里该用空行分段就用空行别依赖单换行这样转换结果最可控。5.4 图片路径与相对引用Markdown 里的图片路径Pandoc 转换时是相对于当前工作目录解析的不是相对于 Markdown 文件所在目录。这是个经典坑。比如你的文件结构是project/ docs/ report.md images/ flow.png在project/目录下执行pandoc docs/report.mdMarkdown 里写是对的。但如果你cd docs再执行路径就得改成依然对但如果你写的是就找不到。最稳的做法是统一在项目根目录执行 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-docassets/template.docx \ --filter mermaid-filter \ --columns100 \ --wrappreserve \ --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 直接输出可转换友好的 Markdown8.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 写作规范立起来——这是我这大半年最大的收获。 AI生成Markdown转Word无损方案：Pandoc处理公式与Mermaid图表
AI 生成的内容落到 Word 里就毁容——这事我踩过的坑能写满一页纸。你让模型输出一份带流程图的方案聊天窗口里看着漂漂亮亮复制到 Word 里Mermaid 代码变成一堆裸文本LaTeX 公式变成\frac{a}{b}这种天书表格列宽拖不动代码块缩进全乱。更气人的是明明内容是对的交付出去却像半成品。这篇就聊一套我自己跑了大半年的工作流把 AI 生成的 Markdown含 Mermaid 图表、LaTeX 公式无损转成 Word 文档公式是真公式、图表是真图、排版能直接交差。适合经常用 AI 写技术文档、方案书、论文初稿又必须交付 Word 格式的人——不管你是刚接触 Pandoc 的新手还是已经被公式图片转 Word折磨过的老手都能从里面抄到能直接用的配置和命令。1. 先搞清楚为什么复制粘贴一定会翻车1.1 剪贴板只认纯文本和富文本不认语义大多数人转 Word 的第一反应是 CtrlC、CtrlV。这个动作的本质是把渲染后的视觉结果塞进剪贴板。问题在于剪贴板里能承载的格式只有两类纯文本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 版开始用 OMMLOffice 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 pandocLinux 用包管理器或直接下二进制。 第二个是**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 搞不定的公式再装一个轻量引擎。真要装选这两个之一MiKTeXWindows 友好按需下载宏包初次安装体积小遇到缺包会自动提示安装。TeX Live跨平台全量一次装全体积大但省心适合长期重度使用。装完后验证xelatex --version有版本输出即可。这里选 XeLaTeX 而不是 pdfLaTeX是因为它对中文和字体的支持更好后面转 PDF 会用到。2.3 Mermaid 渲染两条路选适合你的Mermaid 要变成 Word 里的图必须先渲染成图片。有两条路路线 Amermaid-filterPandoc 过滤器这是最省事的方式。装好 Node.js 后npm install -g mermaid-filter然后转换时加--filter mermaid-filterPandoc 遇到mermaid代码块会自动调用它渲染成 PNG 并嵌入。优点是全自动缺点是依赖 Node 环境且渲染质量受默认配置限制。路线 BMermaid 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:numm:rm:ta/m:t/m:r/m:num m:denm:rm:tb/m:t/m:r/m:den /m:fPandoc 的 texmath 库负责做这个映射。大部分常见符号分数、上下标、求和、积分、矩阵它都能处理但一些冷门宏包、自定义命令、复杂排版比如align环境的某些用法就可能翻车。3.2 行内公式和行间公式的写法规范要让转换顺利源 Markdown 里的公式写法得规范。这是很多人忽略的一点。行内公式用单个美元符号当 $x 0$ 时函数单调递增。行间公式用双美元符号且前后要空行系统满足如下约束 $$ \int_{0}^{T} f(t) \, dt C $$注意行间公式前后不空行Pandoc 有时会把它当成行内公式处理导致排版错乱。这个坑我在处理一份 50 页的方案时踩过排查了半天才发现是空行问题。3.3 实测哪些公式能无损哪些会翻车我拿一批常见公式做了实测结果如下公式类型LaTeX 示例转换结果分数\frac{a}{b}无损原生 OMML上下标x^{2}_{i}无损求和积分\sum_{i1}^{n}无损希腊字母\alpha \beta \gamma无损矩阵\begin{matrix}...\end{matrix}无损分段函数\begin{cases}...\end{cases}无损自定义宏\mycmd{x}翻车显示为原文复杂 align多行对齐部分翻车结论很清楚标准 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 里替换成图片引用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 的属性指定尺寸{ width15cm }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 --columns100二是在 Markdown 里用网格表格grid table显式指定列宽-------------------------- | 字段 | 说明 | | id | 主键自增 | --------------------------网格表格的列宽由---的横线长度决定Pandoc 会把这个比例写进 Word。5.2 代码块的语法高亮与字体Pandoc 转 docx 时代码块默认用等宽字体但不会带语法高亮除非用--highlight-style配合特定输出格式。Word 里想要高亮得靠样式表。我的做法是转 docx 时用--reference-doc指定一个模板文档模板里定义好代码块的样式字体、背景色、边框。这样所有代码块自动套用统一样式。pandoc input.md -o output.docx --reference-doctemplate.docx模板文档的制作方法先随便转一个 docx打开后修改Source Code样式的字体和背景另存为模板。5.3 Markdown 换行在 Word 里的表现差异Markdown 里单个换行行尾不加两个空格在渲染时通常被当成空格不产生新行。但 Word 里你可能希望它真的换行。Pandoc 有个参数控制这个行为pandoc input.md -o output.docx --wrappreserve--wrappreserve会保留源文件里的换行。不过要注意这可能导致段落内出现意外的换行。我的建议是源 Markdown 里该用空行分段就用空行别依赖单换行这样转换结果最可控。5.4 图片路径与相对引用Markdown 里的图片路径Pandoc 转换时是相对于当前工作目录解析的不是相对于 Markdown 文件所在目录。这是个经典坑。比如你的文件结构是project/ docs/ report.md images/ flow.png在project/目录下执行pandoc docs/report.mdMarkdown 里写是对的。但如果你cd docs再执行路径就得改成依然对但如果你写的是就找不到。最稳的做法是统一在项目根目录执行 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-docassets/template.docx \ --filter mermaid-filter \ --columns100 \ --wrappreserve \ --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 直接输出可转换友好的 Markdown8.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 写作规范立起来——这是我这大半年最大的收获。