简介Pandoc 是广为使用的开源文档转换利器支持 Markdown、HTML、LaTeX、Word DOCX、EPUB 等数十种标记格式之间的相互转换在写作、出版、学术排版与技术文档维护中非常实用尤其适合需要批量处理文档格式的开发者、技术写作者和学术研究者。这一压缩包提供 Pandoc 3.6.4 的 Windows 可执行版本共 4 个文件主程序 exe 可直接运行HTML 手册可离线查看参数与用法txt、rtf 文件则包含版权与授权说明整体约 36.04MB解压后无需额外安装环境即可本地调用。当前已有 829 人学习下载。借助包内主程序与配套手册读者可快速完成 Markdown 转 Word/HTML、LaTeX 转 EPUB 等常见转换也能依据手册进一步处理复杂模板、自定义样式或扩展场景对经常交付不同格式文档的用户而言本地离线转换既提升效率也减少在线工具的上传等待和隐私顾虑。1. 为什么文档转换总让人抓狂以及 Pandoc 是什么做技术写作、写论文、整理项目文档的朋友估计都有过这种经历在 Markdown 里排版排得清清楚楚一到要交 Word 给导师或同事时格式全乱表格错位、图片路径失效、代码块颜色丢失手动修排版到深夜。我试过好几款转换工具要么收费要么转换质量堪忧直到遇到 Pandoc这种情况才算彻底结束。Pandoc 3.6.4 是目前开源社区里公认的文档格式转换神器这名字你可能听过但未必清楚它到底强在哪。它是 Haskell 语言写的一个命令行工具核心能力是在无数种文档格式之间做无损转换包括且不限于 Markdown、CommonMark、HTML、LaTeX、docx、epub、PDF、reStructuredText、ODT、Textile甚至还有 Jupyter Notebook 的 ipynb 格式。简单说你手上不管是什么格式的文档它几乎都能给你转成另一种格式而且转换质量远超市面上大部分所见即所得工具的“另存为”功能。这篇博文适合谁看第一类是写技术博客和 API 文档的人用 Markdown 写作、需要输出多种格式第二类是高校学生和科研人员论文和实验报告需要 Word 或 PDF第三类是做文档自动化的工程师想把 Markdown 一键转为带统一模板的 docx。无论你属于哪一类读完这篇都能拿它直接干活。Pandoc 的转换逻辑和传统的“复制粘贴”或者 Word 里的“另存为 PDF”完全不同它内部先把源文档解析成一份抽象的文档树类似一个标准化的中间表示再从这个中间表示渲染成目标格式。这就是为什么它能保持内容的逻辑结构、标题层级、表格、代码块、引用这些信息转换的效果不是“看起来像”而是“结构上就是”。2. 安装 Pandoc 3.6.4 并跑通第一条命令2.1 不同系统的安装方式和验证方法Pandoc 的安装非常友好三个主流平台都有对应的安装包。Windows 用户直接去 GitHub Releases 页面下载 pandoc-3.6.4-windows-x86_64.msi双击安装完会自动加入 PATH无需手动配置环境变量。macOS 用户推荐走 Homebrew一条命令brew install pandoc就搞定装的正是最新稳定版不想用 Homebrew 的话也能下载 pkg 安装包。Linux 用户根据发行版选择 deb 或 rpm 包Ubuntu/Debian 用sudo dpkg -i pandoc-3.6.4-1-amd64.debFedora 系用 rpm 命令。安装完成后打开终端或命令提示符运行pandoc --version看到版本号 3.6.4 就说明环境没问题。这一步看着简单但实际有几个人卡住了最常见的原因是 Windows 下安装完没重开终端PATH 没刷新或者下载了 32 位包在 64 位系统上装不上。如果pandoc --version报“不是内部或外部命令”优先检查这两个地方。我个人的建议是直接装 3.6.4 的最新版本不要图省事用系统源里的旧版。Pandoc 的版本迭代很快新版本不仅修 bug还会增加新格式的转换支持比如 3.x 版本对 epub、Muse、Typst 这些格式的支持就比旧版强了很多。另外它是单文件依赖极少的工具升级成本很低没有理由用老版本。2.2 转换一篇文章需要的最小命令是什么跑通环境后先拿一个最小例子练手。假设你有一个test.md文件内容随便写几行文字加一个标题然后运行pandoc test.md -o test.docx就这么一行Markdown 变成 Word 文档了。这里-o是--output的缩写表示输出文件名Pandoc 会根据输出文件名的扩展名自动判断目标格式。你甚至不用单独指定“我要转成 docx 格式”它自己就知道。同理如果你想转成 HTML、PDF、epub只需要改输出文件的后缀名就行pandoc test.md -o test.html pandoc test.md -o test.pdf pandoc test.md -o test.epub能这么省事的原因在于 Pandoc 内部维护了一套“输入格式 输出格式”的矩阵它在启动时会分别检测输入文件的扩展名和输出文件的扩展名自动匹配对应的 reader 和 writer。理解这一点后你就不会被“这个格式能不能转那个格式”的问题困扰了只要 Pandoc 支持这个格式它就能在任意两种支持的格式间转换剩下的只是某些格式之间的信息损耗问题。2.3 为什么 Pandoc 值得学而不用手写转换脚本有一种听起来更“程序化”的做法是用 Python 的 python-docx 或 HTML 转 PDF 的库自己写脚本但实际操作下来你还是会发现处处是坑。Pandoc 的价值在于它把格式解析和渲染这一层高度抽象化了你不需要自己去处理 DOCX 内部的 XML 结构也不需要自己写 LaTeX 模板它是“格式转换的编译器”你只需要关心内容和输出目标。拿我自己做技术博客的经历来说我所有的文章都以 Markdown 形式存储需要交付 Word 版时运行一行 Pandoc 命令需要做幻灯片时转成 HTML需要生成 PDF 手册时转成 PDF源文件始终只有一份这个操作效率是手动排版完全没法比的。3. 最核心的转换场景Markdown 与 Word 双向互转3.1 Markdown 转 Word 时的样式与结构表现刚才已经能出 docx 了但对中文用户来说直接生成的 Word 文档往往不够精致中文字体、段落间距、标题颜色都和预期有差距。这是因为 Pandoc 默认的 docx writer 会套用一个内置的 reference.docx 模板这个模板的样式是最基础的样式并没有针对中文排版做优化。解决办法是制作一个自定义的 reference 模板文件。先让 Pandoc 生成一份默认模板作为起点pandoc -o custom-reference.docx --print-default-data-file reference.docx这条命令会在当前目录下生成一个custom-reference.docx这个文件本质上是一个普通的 Word 文档你可以用 Word 打开它修改里面的“标题 1”“标题 2”“正文”“首行缩进”等样式保存后后续所有转换都可以套用这份模板pandoc test.md -o test.docx --reference-doccustom-reference.docx这个技巧特别好用你只需要花十几分钟把模板调好一次之后所有文档都能统一排版风格尤其是团队协作或论文写作场景下统一的标题字体、大小写习惯、代码块底色会让文档看起来非常专业。关于样式映射关系再补充一句Markdown 中的一级标题#对应 Word 的“标题 1”样式二级标题对应“标题 2”依此类推Markdown 中反引号包裹的行内代码对应 Word 里的“要点字符”样式多行代码块对应“源代码”段落样式。理解这层映射你就能精准地控制转换结果的样式而不用在 Word 里一个一个改。3.2 表格、代码块、图片这些元素转换时要注意什么Markdown 转 Word 时最让人头疼的三类元素分别是表格、代码块、图片。表格方面Pandoc 转出的 docx 表格默认是 Word 原生表格结构但列宽往往需要手动调整。一个实测有效的做法是在 Markdown 源文件里手动控制表格内容的长度不要让单元格内容过长同时尽量保持每列表格宽度相对均匀这样转出的 Word 表格不会歪七扭八。如果确实需要精确列宽可以在 Word 里用“布局 - 自动调整 - 固定列宽”一次修好然后把这个 docx 作为后续转换的 reference-doc这个坑我踩过很多次这个方式最省事。代码块方面Pandoc 会把 Markdown 的围栏代码块转成 Word 的“源代码”段落样式默认不带背景色不过这在黑白打印场景下反而更清晰。如果需要彩色语法高亮可以在转换时加上--highlight-style参数pandoc test.md -o test.docx --highlight-styletango图片方面Pandoc 处理的是相对路径的图片但有个关键细节转换时的工作目录决定了相对路径的解析基准。比如 Markdown 里写了你需要保证当前执行命令的目录就是 Markdown 文件所在的目录或者使用--resource-path图片所在目录参数指定。这个参数在批量处理文件时特别有用你要构建一个统一的资源目录然后所有 Markdown 文件都能引用同一套图片资源。3.3 Word 转 Markdown反向转换的经验与损耗反向转换Word 转 Markdown这个场景对内容创作者非常实用。我经常收到别人发的 Word 文档想编辑成 Markdown 入库Pandoc 也能做pandoc report.docx -o report.md这个命令会把 Word 转换成为 Markdown同时生成一个media目录把 Word 里的图片全部导出到该目录。但需要注意Word 转 Markdown 的损耗率比 Markdown 转 Word 要高主要体现在三点首先是复杂嵌套表格转换后可能结构变形其次是 Word 里的书签、交叉引用等内部超链接会失效最后是目录TOC字段会变成纯文本丢失目录功能。如果只是为了从 Word 里提取纯文本内容这个损耗基本可以忽略但如果原文档排版非常复杂比如论文里嵌套了多级编号、自定义题注、公式编辑器对象那么转换后需要人工整理。我的经验是反向转换适合用来“获取内容”不适合“完整搬运排版”你要对输出结果做一次结构审查。4. 不让格式丢失的进阶玩法PDF 输出与自定义模板4.1 PDF 输出的几个路径以及中文字体的坑Pandoc 自身不带 PDF 引擎它输出 PDF 依赖底层工具这也是新手最容易劝退的地方。实际上 Pandoc 生成 PDF 有三种路径通过 LaTeX 引擎、通过wkhtmltopdf、通过weasyprint或prince其中 LaTeX 引擎适合学术级排版但对新手不友好尤其中文环境需要额外配置。如果你用的是 LaTeX 路径输出中文 PDF 最常见的坑是缺少 CJK 字体支持。Markdown 文件里有中文直接运行pandoc test.md -o test.pdf大概率报错或输出一堆乱码方块字符这是因为默认的 LaTeX 模板用的是英文编译链没有加载中文字体。一个比较省心的方案是使用xelatex引擎编译并在转换命令里指定-V CJKmainfontNoto Sans CJK SC或你系统中已有的中文字体名pandoc test.md -o test.pdf --pdf-enginexelatex -V CJKmainfontNoto Sans CJK SC我实际用下来如果文档不是大量数学公式其实没必要上 LaTeX。用--pdf-engineweasyprint配合 HTML 中间格式再引入 CSS 样式来控制页面布局对中文的支持反而更友好。不过 weasyprint 需要 Python 环境安装略费事。综合来看最推荐给新手的方法是先用 Pandoc 把 Markdown 转成 HTML再用浏览器自带的打印功能导出 PDF此方式对中文、表格、代码块的支持最为稳定。4.2 用 Markdown 做幻灯片Pandoc 的另一个高频用途除了 Word 和 PDFPandoc 的另一个高频用途是生成幻灯片。你只要在 Markdown 源文件中用# 一级标题来划分幻灯片页然后加上-t参数指定幻灯片引擎就能输出不同格式的幻灯片pandoc slides.md -o slides.html -t revealjs pandoc slides.md -o slides.pptx-t revealjs输出 HTML 幻灯片可用浏览器直接演示支持动画、代码高亮做技术分享非常合适-o slides.pptx输出 PowerPoint 文件适合需要交 PPT 原文件的场景。我做的技术分享和内部培训都是用 Markdown 写稿然后转 PPT 的因为源文件可控、改稿方便幻灯片样式则交给模板统一处理。这个做法的核心收益是“内容与表现分离”。写 Markdown 时只关心逻辑结构PPT 的长相由主题文件决定改样式不用一页页手动拖效率高得多。4.3 结合脚本批量转换与 obsidian/typora 工作流Pandoc 和 Markdown 编辑器的配合也是一条高效路径。我平时写文档用 Obsidian也可以配合 Typora两者都支持 Markdown但导出功能有限Pandoc 正好补齐这个短板。你可以把 Pandoc 配置成一个自定义命令在 Obsidian 里一键把当前文档导出为 docx 或 PDF。再进一步写一个 Shell 脚本来批量转换当前目录下的所有 Markdown 文件for f in *.md; do pandoc $f -o ${f%.md}.docx --reference-doccustom-reference.docx done这个脚本的力量体现在文档批量交付的场景。例如项目迭代时有几十份设计文档都以 Markdown 保存发布时需要全部产出 Word 版本一条命令让所有文件统一套模板输出省去了逐个打开的重复工作。结合 Git 管理源文件还能做到文档版本可追溯改动可审计。5. 常见问题与排查技巧实录5.1 转换时报错先分清是哪一层的错误Pandoc 用着用着难免遇到报错。最常见的几类错误和排查思路我整理成了一个速查表错误现象根本原因解决方式“Could not find data file templates/default.docx”reference-doc 路径无效或数据目录缺失检查--reference-doc的文件是否存在确认路径无中文字符“Unknown writer: pdf”没有指定 PDF 引擎安装 xelatex 或 weasyprint并使用--pdf-engine指定中文字符显示为方块LaTeX 编译链没有加载中文字体使用 xelatex 并设置-V CJKmainfont或转 HTML 后用浏览器导 PDF图片不显示--resource-path未设置或路径错误加--resource-pathimages/确认图片文件存在“Could not read include file”Markdown 里用了include片段文件缺失检查相对路径建议用绝对路径排查问题的核心思路是先确认是 Pandoc 本身的问题还是外部依赖的问题。Pandoc 的报错信息其实相当准确-v参数可以查看完整的执行日志如果日志里出现了 LaTeX 的命令那说明问题出在 LaTeX 环节Pandoc 本身已经完成了解析和渲染的中间步骤。如果你不确定就把--verbose打开逐行看日志比瞎猜高效得多。5.2 关于目录、交叉引用、自动编号的几个经验Pandoc 生成 Word 时默认不会自动生成目录需要在 Word 里手动插入或在模板 docx 中预先放一个目录域。一个实测可行的方案是在reference.docx模板的文档开头预置一个“目录”字段后续所有转换出的 docx 都会自动带上可更新的目录用户在 Word 里右键“更新域”即可刷新页号。如果你的场景是输出 PDF 且对目录有刚性需求LaTeX 路径下的--toc参数可以自动生成带页码的目录而 HTML 转 PDF 场景可以用 CSS 配合工具插件实现。交叉引用和自动编号是 Pandoc 的一个弱项因为 Markdown 本身不支持复杂的交叉引用语法我的建议是不纠结于 Pandoc 本身解决这个问题。要么在 Docx 输出后再用 Word 的题注功能处理图表编号要么在写作时用手写编号这么做对绝大多数场景已经够用了。5.3 如何用 filter 扩展 Pandoc让它听懂你的需求Pandoc 的过滤器filter机制是它最强大的扩展点。简单理解filter 允许你在 Pandoc 完成解析、还没开始渲染之前对文档的抽象表示进行程序化修改。比如你可以写一个 Python filter把文档里所有 Markdown 中的[[链接]]语法统一替换成完整的 HTML 链接或者把图片宽度信息注入到每个图片节点中。安装pandocfilters之后一个最简单的 filter 长这样from pandocfilters import toJSONFilter, Str def uppercase(key, value, format, meta): if key Str: return Str(value.upper()) if __name__ __main__: toJSONFilter(uppercase)运行时指定pandoc test.md -o test.docx --filter./uppercase.py这个 filter 会把文档里所有普通文本改成大写。实际工作中更实用的场景是做一个自动把 Markdown 里的表格第一行设置为重复标题行的 filter或者是在导出 HTML 时给代码块逐行添加行号。filter 虽然需要一点点编程基础但是一旦掌握Pandoc 就不再是固定的“格式转换器”而是一个你完全可控的文档处理流水线。6. 给文档自动化新手的配置建议与工作流参考如果你准备在自己的工作流程里正式引入 Pandoc我给的建议是不要一开始就追求复杂的 filter 和定制模板先把最基础的四件事做顺安装好最新版、掌握-o输出参数、准备一份自己的 reference.docx、知道怎么用--pdf-engine处理 PDF 输出。这四件事覆盖了 80% 的日常需求。进一步推荐的工作流是所有文档统一用 Markdown 编写源文件放在 Git 仓库里用 GitHub Actions 或任何 CI 工具在需要时自动执行 Pandoc 命令产出 docx 和 PDF 作为构建产物。这样团队成员只需维护 Markdown 源文件最终交付格式永远由构建系统统一生成永远不会出现“你改了一版 Word我改了一版 MD最后大家不知道哪份是新的”。这个思路实测在多人协作中特别好用减少了很多因格式不同导致的反复沟通成本。还有一个很容易被忽略的点Pandoc 是一个一直在持续迭代的项目3.6.4 这个版本引入了一些对 EPUB、Typst 等新兴格式的支持优化。如果你正好在做电子书或新版排版工具链的实验项目Pandoc 绝对是值得长期跟进的一个核心依赖。它可以参与的工作流程远不止“Markdown 转 Word”从写书、做笔记、写论文到编译发布文档站几乎每个环节都能出一份力。从我自己的体验来看Pandoc 属于那种“用一天觉得是个小工具用一年发现离不开”的软件。它不追求做一个大而全的编辑器而是把“格式转换”这一件事做到极致真正解决了内容与形式分离的问题。希望这篇基于 3.6.4 实测经验的分享能帮你少走一些弯路尤其是初次接触时最让人困惑的中文字体、模板定制和 PDF 引擎选择这几个坑一次绕过去。本文还有配套的精品资源点击获取
` 方法)
