企业官网建设流程全解析

如果你和我一样，平时写文档习惯用 Markdown，一旦要交报告、发正式文档又得打开 Word，那你大概率经历过这种折磨：把内容从 Markdown 编辑器复制到 Word 里，标题样式全废，代码块缩进全乱，表格变成一坨乱码，图的位置到处乱跑。遇到排版严格的项目，光调格式就能损耗半天。尤其是某次我在赶一份上百页的项目文档时，手工改样式改到崩溃，才下决心把 pandoc 这个命令行工具彻底摸透。折腾了几天之后回过头看，整个过程没有想象中那么难，但坑确实不少。所以我把从安装到实战、再到报错排查的完整过程整理成这篇笔记，给同样需要批量把 Markdown 转成 Word 的人参考。适合谁读：写技术博客的人、团队文档管理员、学生，以及任何一个想把纯文本快速变成规范 Word 文档的人。

1. 为什么需要 pandoc：Markdown 转 Word 的常见困境

1.1 复制粘贴为什么总是失控

大多数人对 Word 转 Markdown 的理解，还停留在“复制、粘贴、手动调”的阶段。你从 Markdown 编辑器里复制一串文本，粘贴到 Word 之后会遇到什么？

首先是标题层级。Markdown 里的# 一级标题、## 二级标题在粘贴到 Word 时往往变成普通段落，顶多保留一个比正文大一点的字号，而 Word 的“导航窗格”和“自动目录”都基于标题样式，这种方式生成的文字根本不具备标题属性。其次是代码块，缩进和等宽字体在粘贴时经常被吃掉，代码变成一团糊在一起的文本。第三是表格，很多 Markdown 编辑器的表格在复制到 Word 时要么变成纯文本，要么每行变成一个独立的段落，想恢复成表格只能靠手工“文本转表格”，过程痛苦得让人想放弃。

注意：这种挫败感并不是因为你不会用 Word，也不是 Markdown 编辑器做得不好。核心问题是“格式信息的丢失”——复制粘贴传输的是文本和粗略的字形，而不是 Word 的样式体系。

1.2 pandoc 到底做了什么

pandoc 不是某个在线转换网站，也不是一个 GUI 软件，它是一个跑在终端里的转换引擎。你可以把它理解为“文档格式之间的翻译官”。它读入一种格式，解析成内部统一的文档模型，再按照目标格式的规范输出。这个模型保存了标题层级、强调、表格、列表、代码块、图片引用、数学公式等结构化信息，所以在 Markdown 转 Word 时，它生成的并不是“看起来像标题”的文字，而是真正带有 Word 内置样式的 Word 文档。

举个例子，你把下面的 Markdown 喂给 pandoc：

# 项目概述 这是一个测试文档。 ## 背景 这里是正文内容。

转出来的 Word 文件里，项目概述会变成 Word 内置的Heading 1样式，背景会变成Heading 2样式。这意味着你在 Word 里可以直接用导航窗格跳转，可以用“引用→目录”一键生成目录。这是复制粘贴永远做不到的。

1.3 它适合谁，不适合谁

适合的人群很明确：大量使用 Markdown 写作、但最终交付物必须或习惯是 Word 格式的人。比如技术团队沉淀文档、学生交论文初稿、自媒体作者整理素材、产品经理写需求说明。文档量越大，pandoc 的收益越明显，因为它是可脚本化、可批量执行的工具。

不太适合的人也有：如果你只是偶尔转一篇短文，并且完全不介意手动调格式，那一只在线转换工具也能凑合。但你要知道在线转换的风险——文档内容经过第三方服务器，敏感信息可能泄露，而且很多线上工具对复杂 Markdown 的解析能力远远不如 pandoc。给它一次机会，你会明白“本地转换”这四个字有多值钱。

2. 安装 pandoc：跨平台实操记录

2.1 安装前先确认是否已经存在

很多人的电脑上其实已经装了 pandoc，自己却不知道，因为有些依赖它的软件会把可执行文件悄悄带进系统。首次操作前，可以打开终端或命令行窗口，执行：

pandoc --version

如果看到类似pandoc 3.x的版本号输出，说明已经安装。如果提示pandoc: command not found，说明要手动安装。版本号建议至少在 2.0 以上，3.x 系列功能更全，对 Word 相关特性的支持更稳。

2.2 Windows 安装

Windows 用户最省事的方式是下载官方安装包。打开 pandoc 官网的下载页，找到.msi格式的安装文件，双击安装，一路 Next 即可。安装完成后，重新打开命令提示符，执行pandoc --version验证。

这里有一个小坑：某些安装包默认路径带空格或者权限受限，安装后命令行提示找不到命令。解决办法是手动把 pandoc 的安装目录（一般是C:\Users\用户名\AppData\Local\Pandoc）加到系统环境变量Path里，或者干脆选择“安装到所有用户”的选项。我见过不少人卡在这一步，以为安装失败，其实只是环境变量没生效。

2.3 macOS 安装

macOS 用户如果装过 Homebrew，一条命令就能搞定：

brew install pandoc

没装 Homebrew，也可以去官网下载.pkg安装包，双击安装。值得提醒的是，苹果芯片机器和 Intel 机器的安装包通常有区分，官网下载页面通常会给出版本选择，认准你自己的架构。

2.4 Linux 安装

Debian/Ubuntu 系发行版直接走软件源：

sudo apt update sudo apt install pandoc

注意软件源里的 pandoc 版本可能偏旧。如果你需要最新版，自己下载性能和可靠性都更好的二进制包更合适——GitHub 的 release 页面有编译好的.tar.gz压缩包，解压后把文件放到/usr/local/bin下面。比起编译源码，这种方式大概五分钟能完成。

2.5 版本差异的第一课

安装完成后，我强烈建议先跑一下：

pandoc --help

你会看到一大堆选项，没必要全背。先记住一点：不同版本的 pandoc 对 Markdown 扩展语法的支持有差异。比如 2.x 时代和 3.x 时代在属性语法、表格扩展上的默认行为就有差别。后面要是发现命令在某个地方表现不对，先检查版本号，很多问题其实是版本不一致造成的。

提示：pandoc 的功能只通过命令行暴露，新手容易觉得它不友好，但这也意味着它可以稳定地嵌入脚本。一个仅几 MB 的可执行文件，却能在一秒内完成几百页文档的格式转换，性能和可靠性远超 GUI 工具。

3. 核心转换命令与样式控制

3.1 第一条转换命令

安装完成后，到 Markdown 文件所在目录，执行：

pandoc input.md -o output.docx

这是最简形态的命令。input.md是你的源文件，-o后面的output.docx是输出文件。pandoc 会根据扩展名自动判断输入输出格式。.md默认识别为 Markdown，.docx默认识别为 docx。执行完，当前目录下就会多出一个 Word 文档。

我第一次执行这条命令时，心里想的是“就这么简单？”真的就是这么简单。但打开 Word 之后会发现一个问题：默认字体是西文字体，中文显示可能会回退成系统默认字体，看起来像“宋体夹着 Calibri”，整体观感粗糙。这时候就需要用样式模板来约束最终效果。

3.2 常用参数详解

随着处理的文档越来越复杂，你需要掌握这些参数：

这些参数可以自由组合。例如：

pandoc input.md -o output.docx --toc --highlight-style=tango

为什么--toc要谨慎用？因为它生成的目录本质上是静态文本，Word 打开后不会自动关联页码。如果要“点一下能跳转、右键能更新域”的那种动态目录，更靠谱的做法是让 pandoc 只负责把标题变成样式，然后在 Word 里通过“引用→目录→自动目录”来生成。后面我会在问题部分进一步讲。

3.3 用 reference-doc 模板控制 Word 样式

想让转出来的 Word 自带好看的中文字体和统一的排版风格，最核心的机制是 reference-doc 模板，也就是参考文档。思路是先让 pandoc 导出一个默认的 docx 模板，你在 Word 里把它打开，修改各级标题、正文、代码块的字体和字号，保存回去，之后所有转换都套用这份样式。

导出默认模板的命令是：

pandoc -o custom-reference.docx --print-default-data-file reference.docx

Windows 下建议用：

pandoc -o custom-reference.docx --print-default-data-file reference.docx

操作方式：生成的custom-reference.docx用 Word 打开，此时你会看到它里面标注了Normal、Heading 1、Heading 2、Source Code等样式。修改它们的方法：在 Word 里找到“开始→样式”面板，在对应样式上右键→修改，把字体设成中文字体，例如正文用宋体小四，标题用黑体三号。

改完保存，然后转换命令变成：

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

这样出来的 Word 文档，所有段落会自动套用你改过的样式。原理在于 pandoc 生成的 docx 并没有把样式写死，而是引用 Word 内置的样式名称。换成你自定义的 reference 文档之后，它把对应名称的样式定义替换掉了。这个概念一旦理解，就不再需要每次转换后手动改字体。

实操心得：做模板时最重要的两个样式是Normal和Heading 1。前者决定正文观感，后者决定标题层级。多数人只改这两个就能满足 90% 的日常需求。中文排版还有一个细节：Word 里正文的“对齐方式”默认是两端对齐，你可以在模板中直接改掉，顺便把段前段后间距调整好。

3.4 批量转换与自动化脚本

当文档数量多到几十上百份时，一条条执行命令就不现实了。好在 pandoc 天然适合脚本。

在 Linux/macOS 的 bash 里可以写一个循环：

for f in docs/*.md; do pandoc "$f" -o "${f%.md}.docx" --reference-doc=custom-reference.docx done

在 Windows PowerShell 里可以这样：

Get-ChildItem docs -Filter *.md | ForEach-Object { pandoc $_.FullName -o ($_.BaseName + ".docx") --reference-doc=custom-reference.docx }

脚本化最大的好处是稳定可复现。同一个团队的文档，不管是谁来跑这个脚本，输出结果完全一致。对于“每次都要上交统一格式文档”的场景，这个价值怎么强调都不过分。

4. 常见问题与排查技巧实录

4.1 中文乱码和字体异常

转换后的 Word 文件里中文出现乱码，原因通常不是 pandoc 转坏了，而是文本本身编码问题。Markdown 源文件如果是 GBK/GB2312 编码，pandoc 默认按 UTF-8 解析，就会产生乱码。解决办法是想办法把源文件转成 UTF-8，VS Code 编辑器右下角可以直接改编码并重新保存。

更常见的“看起来难受”问题其实是字体回退：Word 里中文字体没有显式指定，显示出来的字形很怪。这就是必须用 reference-doc 模板的原因。一份合格的模板，把Normal的字体设为“宋体”或“微软雅黑”，Heading系列设为“黑体”或“思源黑体”，转换之后的文档就能保持稳定的中文排版。

4.2 图片丢失或路径错乱

转换文档时，如果 Markdown 里引用的是相对路径图片，比如![截图](./images/a.png)，而 pandoc 的执行目录和文档所在目录不一致，图片就会加载不到。解决办法是执行命令时先cd到 Markdown 文件所在目录，或者用--resource-path指定一个额外搜索路径：

pandoc chapter1.md -o chapter1.docx --resource-path=.

还有一种情况：图片路径里带了中文或空格，命令行解析会出问题。遇到这种场景，建议把整个路径放在引号里，并及时检查源文件中的路径写法。其实最稳妥还是规范命名文件，从一开始就别用空格和中文字符命名图片。

4.3 表格列宽错乱和单元格合并

标准 Markdown 管道表格转 Word 后通常是规整的，但如果表格列数很多、每列内容长短悬殊，Word 打开后列宽容易失衡。常规解决办法是修改 reference-doc 里的“Table”样式，或者转完之后用 Word 的“布局→自动调整→根据内容调整表格”。对更复杂的可视化表格，比如需要行合并、列合并的场景，Markdown 本身并不擅长描述，通常需要在 Word 里手动补。

避坑建议：如果你的 Markdown 表格是从其他格式粘贴过来的带有多行表头、合并单元格的信息，转换前先把它们在 Markdown 里简化成标准表格。pandoc 不会像人一样帮你排版复杂的单元格结构。

4.4 数学公式显示异常

如果你在 Markdown 里写了 LaTeX 数学公式，比如$E = mc^2$，pandoc 默认会尝试转成 Word 的原生公式。这对很多公式是有效的，打开 Word 后可以直接编辑。但遇到复杂公式，比如带矩阵、多行对齐的符号，转换结果可能出现结构错位。

有两个替代方案。其一，用--webtex参数，公式会被渲染成网络图片插进 Word，观感稳定但公式无法在 Word 里编辑。其二，转成 docx 后用 Word 的“公式”工具手工修正。我的经验是：普通技术文档用默认转换就够，论文级别的复杂公式在转换后一定要抽查。

4.5 代码块样式和高亮

pandoc 支持代码块语法高亮，默认会用内置的一种高亮风格。如果你想自定义颜色，用：

pandoc input.md -o output.docx --highlight-style=tango

可选的风格有pygments、kate、monochrome、breezedark、espresso等。在 Word 中这种高亮本质上是通过字符颜色和背景色实现的。需要注意，如果这一段代码排版要求特别严格，建议在参考模板里单独设置Source Code样式，让字体变成等宽字体，比如“Consolas”或“JetBrains Mono”。

4.6 目录生成和导航问题

我在前面提过，--toc生成的目录是静态的。如果你需要自动更新的 Word 目录，最合理的流程是：先用 pandoc 转换时省略--toc，让所有标题变成Heading 1、Heading 2样式，再用 Word 打开后选择“引用→目录→自动目录”生成。这样做的好处是目录完全符合 Word 的导航体系，可以按 Ctrl 点击跳转，也可以右键“更新域”刷新页码。

4.7 问题速查表

5. 更多玩法：反向转换与工作流整合

5.1 Word 转回 Markdown

很多人只关注 Markdown 转 Word，其实 pandoc 的反向转换也很实用。用别人交付的 Word 文档提取内容，转成 Markdown 再归档或继续编辑：

pandoc report.docx -o report.md --extract-media=./assets

--extract-media会把 Word 里的图片按二进制文件导出到assets目录，Markdown 文档里用相对路径引用。要注意的是，Word 里的复杂排版，比如文本框、艺术字、页眉页脚，转换后会有信息丢失，这很正常。这类工具最适合的场景是快速提取文字内容，而不是追求完美复刻样式。

5.2 输出 PDF、HTML、Epub

pandoc 不只是 Markdown 转 Word，它也能输出 HTML、PDF、Epub、LaTeX 等格式。PDF 输出需要额外安装 LaTeX 引擎，配置成本较高，我更推荐一种轻量方案：先用 pandoc 转 HTML，再用浏览器打印成 PDF；或者直接输出 docx，用 Word 另存为 PDF。后一种方式对绝大多数办公场景完全够用。

HTML 输出是快速预览的好方式：

pandoc input.md -o output.html --standalone --toc

--standalone会把 CSS 和元信息打包成一个独立的 HTML 文件，双击就能浏览。你要是想给同事分享一份“不需要 Word 也能看”的文档，这个命令最方便。

5.3 与编辑器配合的自动化工作流

最后分享一个日常组合拳。我把 pandoc 命令挂进了代码编辑器里的“任务”，每次写完一个章节，按一个快捷键就能生成最新版的 Word 文档。具体做法可以在 VS Code 的 tasks.json 里定义：

{ "version": "2.0.0", "tasks": [ { "label": "md to docx", "type": "shell", "command": "pandoc ${file} -o ${fileBasenameNoExtension}.docx --reference-doc=custom-reference.docx", "group": "build" } ] }

保存后按快捷键调出任务面板，选择这个任务。这样就把“写文档”和“生成交付物”拆成两件事：写的时候只管内容质量，交付时跑一次任务，全程不需要打开 Word。如果团队有统一的规范，把这份模板和脚本放进项目仓库，全团队用同一套转换逻辑，交付格式的混乱问题自然就消失了。

我个人在实际操作中最深的一个体会是：pandoc 不是那种“用一次就卸载”的小工具，而是一个可以沉淀进团队协作流程的基础设施。你真正精通的不是某条命令，而是“用结构化内容驱动输出物”的思路。遇到任何文档格式问题，先试试把内容整理成干净的 Markdown，再用 pandoc 分发，你会少掉很多手工排版的烦恼。