先说结论如果你经常需要在 Markdown、Word、HTML、PDF 甚至 epub 之间来回转换文档Pandoc 就是那个你迟早会装上、装上之后就再也离不开的工具。这货本质上是一个文档格式转换器但它的能力早就超出了“转换”这两个字。你可以用 Markdown 写一篇论文然后用一条命令导出带目录、带参考文献、排版工整的 Word 或 PDF你也可以把一堆 HTML 网页快速转成结构干净的 Markdown 笔记你甚至能让 GitHub 风格的 README 秒变一份能直接打印的 Word 文档。它不挑平台不挑编辑器只要你的电脑能跑命令行它就能干活。这篇文章我从零开始讲 Pandoc 的安装和基本使用方法同时会带上很多我在实际使用中踩过的坑和总结出来的技巧。无论你是学生、技术写作者、产品经理还是偶尔需要处理文档格式的打工人按这篇文章走一遍基本就能上手干活了。1. 为什么是 Pandoc而不是直接复制粘贴很多人第一次听到 Pandoc 的第一反应是我直接从网页复制到 Word 里不就行了遇到格式错乱再手动调一调为什么要学一个命令行工具这个问题的答案藏在“文档”这件事的本质里。文档内容的流转最核心的问题不是复制而是格式语义的丢失。你从 Markdown 复制到 Word标题结构、代码块、强调、引用、列表层级这些信息在粘贴之后往往会变成一堆混乱的纯文本或错误的内联样式。你从网页复制到 Word往往还带着一堆垃圾样式清理的时间比重新写一遍还长。Pandoc 做的事情是先把源文档解析成一种中间的抽象语法树再从这个语法树生成目标格式。这个过程保证了标题还是标题、代码块还是代码块、链接还是链接而不是变成一堆肉眼不可见但一调格式就崩的样式污染。再往深一层说Pandoc 支持在几十种标记语言之间做转换包括 Markdown、reStructuredText、HTML、LaTeX、Docx、ODT、epub、Org-mode、MediaWiki 等等。这意味着它可以作为你整个写作流程的“格式枢纽”。你在本地用 Markdown 写内容最终可以根据需求输出不同格式给同事的 Word 版本、给线上平台的 HTML 版本、给 Kindle 的 epub 版本甚至提交给出版社的 LaTeX 版本。内容只写一次导出无数次这才是 Pandoc 真正的价值。另外还要提一点Pandoc 的命令行设计非常克制且统一几乎所有转换都用同一种模式pandoc 输入文件 -o 输出文件再附加不同选项。这种设计大大降低了记忆成本你学会一个场景的命令其他场景就能举一反三。所以我个人的建议是不要把它当作一个“转换工具”去学而是当作“写作底层设施”去理解。你一旦习惯了这种“纯文本写作任意格式导出”的工作流就很难再回到那种“在一个工具里写死所有格式”的旧模式。2. 安装 Pandoc一条命令或一个安装包的事安装方面的门槛其实很低。Pandoc 提供 Windows、macOS、Linux 三个平台的安装方式也提供源码编译。下面我按平台展开讲同时会区分“快速安装”和“管理工具安装”两种路径你自己看情况选。2.1 Windows 环境下的安装Windows 用户最简单的做法是去 Pandoc 官网的 releases 页面下载 .msi 安装包双击安装一路下一步。装完之后需要手动确认一下环境变量有没有生效因为很多人第一次装完在终端里敲 pandoc --version 会提示“不是内部或外部命令”原因就是安装目录没有加入 PATH。如果你喜欢用包管理器也可以选 choco 或 scoopchoco install pandoc # 或者 scoop install pandoc用包管理器安装的好处是后续升级方便一条命令就能完成。如果你经常用 Windows 做文档处理我很推荐 Scoop它默认为用户级安装不需要管理员权限而且软件互相隔离出问题也好清理。安装完成后开一个全新的命令行窗口运行pandoc --version看到一长串版本信息和编译环境说明就说明安装成功了。这里注意一点如果是在 PowerShell 里运行要确认当前用户 PATH 已经刷新如果运行命令前就是老窗口即使系统已经装好了也可能提示找不到命令关掉窗口重开一次基本能解决。2.2 macOS 环境下的安装macOS 用户最方便的方式是用 Homebrewbrew install pandoc如果你需要更多扩展能力比如把 Markdown 转 PDF 时依赖的 LaTeX 环境可以安装包含更多组件和公式字体支持的版本brew install --cask basictex这一步属于可选项但强烈建议经常导出 PDF 的人装上否则后面会遇到“PDF 引擎缺失”的报错。如果你的 macOS 上还没装 Homebrew也可以直接下载 pkg 安装包手动安装效果一样。安装完成后同样先验证pandoc --version2.3 Linux 环境下的安装Linux 发行版很多包管理器各不相同。Ubuntu、Debian 系统可以用sudo apt update sudo apt install pandocCentOS、RHEL、Fedora 这类系统可以用 yum 或 dnfsudo yum install pandoc # 或 sudo dnf install pandoc不过在部分发行版的默认源里Pandoc 的版本可能比较旧。如果你对版本有要求建议直接去 GitHub releases 页面下载对应架构的 tarball 包解压到 /usr/local/bin 之类的位置。比如 amd64 架构的 Linux 版本wget https://github.com/jgm/pandoc/releases/download/3.1.11/pandoc-3.1.11-linux-amd64.tar.gz tar xvzf pandoc-3.1.11-linux-amd64.tar.gz sudo cp pandoc-3.1.11/bin/pandoc /usr/local/bin/这样装的好处是版本最新避免发行版源里那种“能用但功能缺一截”的问题。2.4 安装后环境验证无论哪个平台都建议装完第一件事是跑一遍这个命令确认默认工作正常echo # Hello Pandoc | pandoc -t html输出应该是h1 idhello-pandocHello Pandoc/h1看到这样的输出说明解析和渲染链路已经通了。注意如果这里报错先检查 Python 里有没有一个也叫 pandoc 的包。某些环境里容易混淆。确认你运行的是 /usr/local/bin/pandoc 或者 C:\Program Files\Pandoc\pandoc.exe 这个二进制文件而不是某个同名脚本。3. 基本使用一条命令打通常见格式转换安装只是热身真正有意思的是 Pandoc 的使用。核心模式一句话pandoc 源文件 -o 目标文件。源文件的格式和输出格式通常不需要手动指定Pandoc 会通过文件扩展名自动判断。3.1 最常用的转换命令几个最常见的转换例子# Markdown 转 Word pandoc input.md -o output.docx # Markdown 转 HTML pandoc input.md -o output.html # Word 转 Markdown pandoc input.docx -o output.md # HTML 转 Markdown pandoc input.html -o output.md # 多个 Markdown 文件合并转成一个 Word pandoc chapter1.md chapter2.md chapter3.md -o book.docx # Markdown 转 epub pandoc input.md -o output.epub从这些命令里能发现一个规律Pandoc 不区分输入和输出格式是否“同族”。Word 这种二进制格式它能读Markdown 这种纯文本它也能读。输入输出可以自由组合这才是它真正的威力。我自己最常用的是 Markdown 转 Word 以及 Word 转 Markdown。前者用于对接同事后者用于把别人发来的文档整理成自己知识库里的 Markdown 笔记。3.2 关于 -s 参数为什么默认转换不够用很多新手会发现直接 pandoc input.md -o output.html 生成的 HTML 没有 head 和 body 结构看起来像一串碎片。这是因为 Pandoc 默认情况下只转换“文档片段”而不是“完整文档”。想要生成一个完整的 HTML 文件需要加上 -s 或 --standalonepandoc input.md -o output.html -s加上 -s 之后Pandoc 会把元数据和模板组装进去生成一个包括、 、标签在内的完整文件。对 Word 和 PDF 来说这个差异不明显但如果后续要打开浏览器预览或者生成需要自包含的 HTML-s 就很关键了。这里多说一句Pandoc 的模板机制非常强大生成 HTML 时你可以指定自己的自定义模板也可以直接控制 CSS。不过那是进阶话题基础阶段你只要记住“用 -s 生成完整文件”就够了。3.3 直接控制输出格式有时候文件扩展名不能完全满足需求或者你想要一种不常见的输出格式这时候用 -t 参数指定pandoc input.md -t html5 -s -o output.html pandoc input.md -t docx -o output.docx pandoc input.md -t markdown_strict -o output.md-p 参数这个重要下一篇再讲。这里仅作为例子展示 -t 的用法。用 -t 控制输出时Pandoc 不会生成文件而是把结果打印到终端。想保存成文件还是得用 -o。但如果只要预览不写 -o 直接跑到标准输出效率更高。# 在终端里直接预览转换结果 pandoc input.md -t html3.4 从非文件输入读取管道和粘贴板Pandoc 也支持从标准输入读取内容。这意味着你可以把一段 Markdown 文本直接通过管道传给 Pandoc而不需要新建文件echo # 标题 | pandoc -t html这个特性在处理临时任务时非常实用。比如你从网页上复制了一段带标签的 HTML想在终端里快速转成干净的纯文本可以这么用echo p这是 b加粗/b 文本/p | pandoc -f html -t plain输出这是 加粗 文本不需要保存临时文件不需要打开编辑器一条命令搞定。这种“轻量管道”用法是 Pandoc 在脚本化工作流里的一个核心优势。4. 从 Markdown 到 Word/PDF/学术写作这些参数决定输出质量基本转换能用了接下来要处理真实写作中更挑剔的需求样式、中文字体、目录、参考文献。这一节是实操当中最耗时间也最看功力的一部分我会把参数细节和它们背后的原理拆开讲。4.1 用 reference doc 控制 Word 样式直接 pandoc input.md -o output.docx 生成的 Word 文档能用但样式很“素”标题字体、字号、行距、页边距都是默认值。如果你需要在正式场景交付比如给领导看的汇报、给客户提交的方案默认样式就不太够了。Pandoc 提供了一种机制叫“reference doc”。你可以先让 Pandoc 生成一个 Word 文件然后把它的 styles.xml 改成你自己的规范最后每次转换时用 --reference-doc 指定这个模板# 首次生成参考模板 pandoc -o custom-reference.docx --print-default-data-file reference.docx custom-reference.docx这个命令生成的 custom-reference.docx 中包含所有 Pandoc 会用到的 Word 样式比如“标题 1”、“标题 2”、“正文”、“代码块”、“脚注”等。你只需要在 Word 里打开它把每个样式的字体、字号、颜色、间距调成你满意的效果保存然后每次转换时调用pandoc input.md -o output.docx --reference-doccustom-reference.docx这样生成的 Word 文档会带上你预设的样式不用二次手调标题。注意reference doc 里不是你写的内容而是样式模板。改的时候不用管里面的文字只管样式定义。另外不同版本的 Pandoc 生成的 reference.docx 略有差异建议升完级后重新生成一次参考文档否则可能出现样式映射错位。4.2 使用 LaTeX 引擎生成 PDFPandoc 本身不产 PDF它是靠 LaTeX 引擎来完成 PDF 渲染的。默认情况下Pandoc 会用 pdflatex 作为引擎但这个引擎对中文支持比较麻烦。很多人第一次用 Pandoc 转 PDF 时遇到中文乱码或“Missing character”警告问题大多出在这里。一个常见做法是换成 XeLaTeX 引擎并在命令行里指定中文字体pandoc input.md -o output.pdf --pdf-enginexelatex \ -V mainfontNoto Serif CJK SC \ -V sansfontNoto Sans CJK SC \ -V monofontNoto Sans Mono CJK SC \ -V geometry:margin2.5cm这里 -V 是设置变量会传到 LaTeX 模板里。mainfont 控制正文字体sansfont 控制无衬线字体monofont 控制等宽字体。具体字体名字要和你系统里已经安装的字体一致。macOS 上一般可以换成“PingFang SC”或“Songti SC”Linux 上常见的是 Noto CJK 系列Windows 上一般是“SimSun”或“Microsoft YaHei”。如果你不需要复杂排版只想快速输出一份看起来还行的 PDF也可以考虑用 wkhtmltopdf 或 weasyprint 这类 HTML 转 PDF 工具做后端pandoc input.md -o output.pdf --pdf-engineweasyprint这种方式的优点是对中文字体支持更友好因为走的是 HTMLCSS 渲染路径不依赖 LaTeX 字体配置。缺点是排版精细度不如 LaTeX但应付日常文档足够了。4.3 让 Markdown 里的图表自动编号pandoc-crossref 过滤器Markdown 本身不支持“图 1”“表 2”这种自动编号。如果你写的是技术文档、实验报告或学位论文图表编号几乎是刚需。Pandoc 的过滤器机制就是为这类需求准备的。先安装 pandoc-crossref然后追加支持交叉引用的写法。例如在图片下方加一个带标签的标题{#fig:architecture} 如图 fig:architecture 所示系统采用前后端分离架构。然后转换时启用过滤器pandoc input.md -o output.docx --filter pandoc-crossref这样生成的文档里“如图 1 所示”就会自动对应到具体的图片编号。表格、公式、章节引用都可以用类似方式处理。一旦文档篇幅长了这种自动编号能省掉大量手工维护的痛苦。pandoc-crossref 的安装也很简单Windows/linux/macOS 都有预编译二进制下载后放到 PATH 目录即可。也可以直接用包管理器比如# macOS brew install pandoc-crossref4.4 参考文献管理从 BibTeX 到自动生成引用学术写作离不开参考文献。Pandoc 原生支持 BibTeX 和 CSL JSON 格式的参考文献数据。最常用的流程是准备一个 BibTeX 文献库比如 references.bib在 Markdown 里用 key 这种语法插入引用转换时用 --citeproc 参数和 --csl 参数指定引用样式。示例引用写法需要引用的观点 [knuth1984] 表明……转换命令pandoc input.md -o output.docx \ --citeproc \ --bibliographyreferences.bib \ --cslieee.csl这样不仅能在正文中生成正确的“作者年份”或“编号”格式引用还能在文末自动生成参考文献列表。CSL 样式文件可以到 zotero 的样式仓库里找IEEE、APA、GB/T 7714 这些都有现成的。这里需要说明一点旧版 Pandoc 需要单独安装 pandoc-citeproc 过滤器但 2.11 版本之后--citeproc 已经内置不需要额外装过滤器。如果你看到网上教程还在讲“pandoc-citeproc”先确认一下你的 Pandoc 版本。技巧如果只需要一个简单的参考文献列表不需要复杂的引用格式可以在转换时省略 --cslPandoc 默认会使用一种简洁的作者-年份样式基本能满足日常非学术写作需求。5. 常见问题与排查技巧实录Pandoc 整体很稳但实际使用中仍然有一些高频问题。我把自己踩过的坑和排查思路整理成一个速查表按症状分类方便你遇到问题直接对照。症状常见原因解决思路命令找不到安装未完成或 PATH 未配置重新安装或手动把安装目录加入 PATHmacOS/Linux 检查 /usr/local/bin 是否在 PATH 中中文 PDF 乱码LaTeX 引擎或字体配置问题换用 --pdf-enginexelatex 并指定中文字体见 4.2 节“Unknown source format”输入文件扩展名不在 Pandoc 支持列表用 -f 参数显式指定输入格式比如 -f markdown“Cannot parse” 类似报错Markdown 语法某处破坏了解析检查是否存在未闭合的代码块、表格或 HTML 块可用 --verbose 看具体位置图片显示不出来图片路径含空格或中文或相对路径不对用引号包裹路径或使用相对并转义空格在 Markdown 里建议把空格改成 %20 或用下划线Word 样式不对没有使用 reference doc用 --reference-doc 指向自定义模板见 4.1 节转出的 HTML 碎片化没有加 -s加 -s 或 --standalone 生成完整 HTML 文件参考文献不生效版本旧或缺少 --citeproc确认 Pandoc 版本2.11并使用 --citeproc 而不是 --filter pandoc-citeproc公式无法渲染缺少 LaTeX 公式字体或环境安装 basictex 或完整 TeXLive/MiKTeXWord 导出时用自带 OMML 公式无需 LaTeX下面我再挑几个高频问题展开讲因为简单表格只能给思路有些坑需要看细节。5.1 安装后“pandoc 不是内部或外部命令”这个在 Windows 和部分 Linux 终端环境里最常见。Windows 上安装位置一般默认在 C:\Program Files\Pandoc检查一下这个目录是否在系统 PATH 里。如果用的是跨平台终端工具比如 Git Bash 或 WSL 中的某个 shell有时候系统 PATH 没同步重启终端或注销再登录即可。还有一种隐蔽情况你明明在某个 conda 虚拟环境里装过 pandoc但它其实是一个 Python 包和真正的 Pandoc 二进制不是一回事。这种环境里运行 pandoc 可能会进入 Python 模块的逻辑。建议直接用 which pandoc 或 where pandoc 查看实际路径确保执行的是 Pandoc 的二进制文件。5.2 从 Word 转 Markdown 后图片和样式丢失Word 转 Markdown 时Pandoc 默认会把图片提取到单独的媒体目录里同时在 Markdown 里使用相对路径引用。如果后续你移动了 .md 文件却没有同时移动 media 目录图片就找不到了。解决办法是转换时把输出文件和媒体目录放在一起或者用 --extract-media 参数明确指定提取路径pandoc input.docx -o output.md --extract-media./assets这样图片会统一存到 assets 目录Markdown 里引用的路径也会自动带上 assets/ 前缀。之后你想把整个文件夹搬走也记得把 assets 目录一起搬走。另外Word 转 Markdown 时如果文档里有很多自定义样式的标题Pandoc 可能把它们识别为纯文本或段落格式。这时候先检查 Word 文档里的标题到底用的是样式还是手动加粗一个技巧是先在 Word 里把标题样式规范化全部应用“标题 1”“标题 2”等内建样式再转 Markdown结构保留基本无压力。5.3 转 PDF 时“xelatex not found”这个报错意思是你的电脑上没装 XeLaTeX 引擎。选 --pdf-enginexelatex 之前必须先确认系统中已安装 TeX Live、MiKTeX 或 BasicTeX。如果你只是偶尔需要转 PDF又不想装一个几百兆的 TeX 全家桶可以先用 --pdf-engineweasyprint 或 wkhtmltopdf 这类更轻量的方案。我个人的习惯是正式学术场景用 XeLaTeX日常快速输出用 weasyprint。前者输出精品后者只要快和美就够了。两者可以共存不冲突。5.4 表格转换后格式错乱Pandoc 在 Markdown 和 Word 之间的表格转换整体挺好但如果源表格使用了复杂的合并单元格、嵌套表格或跨页表头转换时很容易出现错位或变成纯文本。几年前我用 Pandoc 把一个带大量合并单元格的 Word 表格转成 Markdown结果表格结构全丢内容被压缩成一行。后来学乖了复杂表格要么用 PDF 或 LaTeX 保留原始排版要么在 Markdown 里改用 pipe table 这种简单结构再要么直接在 Word 模板里留占位符最后人工调整。所以如果你要转换的表格特别复杂建议先确认 Pandoc 对这类结构支持有限做好人工修复的准备。如果你要转换的表格是简单二维表那 Pandoc 表现非常稳定放心用。5.5 为什么转换结果和你预期的不完全一致这是一个很常见的“问题”但严格来说不是 bug。Pandoc 只负责“结构转换”不负责“视觉还原”。同一份 Markdown 在不同的输出目标里样式天然会不一样因为 Word 的样式体系、HTML 的 CSS 体系和 LaTeX 的字体体系完全是三套东西。如果你希望三个输出长得“一模一样”那需要做大量模板定制这在技术上可行但代价远超收益。我的建议是结构语义最重要视觉细节放在目标格式里调。Markdown 里保证标题层级、代码块、引用、超链接这些语义正确到了 Word 里用 reference doc 统一风格到了 HTML 里用 CSS 调整观感。这样才是“一份内容多处复用”的正确姿势。6. 一些场景化的用法示例既然安装和基础命令都讲了我再分享几个我实际工作中高频使用的综合场景。这些例子能帮你理解前面讲的参数怎么综合应用同时也能给你一些“原来还能这么用”的灵感。6.1 批量转换脚本把整个目录的 Markdown 转成 Word如果你手头有几十个 Markdown 文件要统一转成 Word一条命令加 shell 循环就搞定for f in *.md; do pandoc $f -o ${f%.md}.docx --reference-doccustom-reference.docx done这里${f%.md}是 shell 参数扩展作用是去掉文件名的 .md 后缀再拼上 .docx。批量处理时会遇到一个问题个别文件如果有特殊字符或语法错误循环会中断。保险做法是在命令前加 set e或者用 find 配合 while read 逐行处理find . -name *.md -print0 | while IFS read -r -d f; do echo 转换中$f pandoc $f -o ${f%.md}.docx --reference-doccustom-reference.docx done加 -print0 和 -d 是为了应对文件名带空格的情况Windows 上用 Git Bash 这样处理也有效。6.2 自动生成带目录的 HTML如果你要在线上发布文档可以直接把 Markdown 转成带目录导航的 HTML。用 -T 设置标题--toc 生成目录--toc-depth 控制目录层级--css 指定样式文件pandoc input.md -s --toc --toc-depth3 \ --metadata title我的技术文档 \ --cssstyle.css \ -o output.html这个输出很适合作为内网知识库或静态博客的单页文档。如果你还想更高阶一点还可以把生成的 HTML 用工具继续转成 PDF这里不多展开。6.3 用 Pandoc 做技术写作的“中间层”以前写技术方案我常常先在 Word 里排版很久后来换了套流程Markdown 写内容Git 管理版本最后用 Pandoc 一键导出交付文档。客户要 Word 就出 Word要 HTML 就出 HTML要 PDF 就出 PDF。这套流程最大的好处有三点第一内容与样式分离改内容不会破坏样式调样式不需要翻遍全文第二版本管理变得清晰每一处改动都有记录不会出现“最终版2最终版3”的混乱第三分发格式随时可以定制交付不同客户时不需要另做一份。如果你想尝试这套流程我建议从最小的改动开始先把自己的笔记从 Word 转到 Markdown然后每天用 Pandoc 导出一份 Word 存档。等你习惯了再把真正的正式文档迁移过来。7. 一点个人心得最后分享几个我长期使用下来的体会。Pandoc 的文档格式转换能力很强但用好的关键不是背命令而是理解“结构语义”这个概念。在你写 Markdown 时标题层级是结构加粗斜体是语义到了 Word 里结构对应样式语义对应字符格式。只有源文档结构清晰Pandoc 才能生成结构清晰的目标文件。这是我踩了无数坑之后最深的一点体会。另外别一上来就想学几十种格式转换。把“Markdown 转 Word”“Markdown 转 HTML”“Word 转 Markdown”这三条最常用的路径彻底玩透就已经解决了日常 90% 的需求。剩下的格式遇到具体需求时再针对性查文档效率反而更高。再分享一个小技巧Pandoc 有个 -v 参数会在调试时输出详细日志命令执行失败时不妨先加 -v 跑一遍它给的错误信息虽然看起来吓人但往往能直接指出问题所在比闷头改命令行高效得多。以及记得定期升级 Pandoc 版本新版本在解析某些语法格式和生成 DOCX 时经常有性能提升和 bug 修复长年不升级的话很容易遇到“网上代码能用但我的就是不行”的情况。把这个工具装好花一晚上把基础命令练熟后面省下的时间绝对值得。