用 Pandoc 之前，先学会看下载页：一次真实的跨平台踩坑记录用 Pandoc 之前，先学会看下载页：一次真实的跨平台

用 Pandoc 之前，先学会看下载页：一次真实的跨平台踩坑记录

我经常需要把 Markdown 笔记转成 Word 或 PDF 发给同事。以前我总是一上来就 pandoc input.md -o output.docx，直到有一次在 Windows 上连续失败三次，才意识到问题不在命令，而在“下载页”上我没读明白。今天就用 Pandoc 为例，聊聊我如何系统地读一个开源软件的下载页，以及那些容易忽略的边界情况。

下载页上到底有什么？先别急着点绿色按钮

打开 Pandoc 的下载页（比如 GitVaults 上的镜像页），第一眼是版本号和“Download”按钮。但真正有用的信息藏在三处：平台标识、文件命名规则、系统依赖说明。

我这次在 Windows 10 上操作，页面列出了 windows-x86_64.zip 和 windows-x86_64.msi 两种格式。第一次我直接下了 .zip，解压后里面有 pandoc.exe 和一个 COPYRIGHT 文件。看起来没问题，但运行 pandoc --version 时报错说缺少 libgcc_s_seh-1.dll。这就是典型的“绿色版”陷阱——没有安装系统依赖。

正确做法是：先看下载页上有没有“System requirements”或“Dependencies”小节。Pandoc 官方页明确写着“Windows builds require MSVC runtime”，但很多镜像页不写。后来我改用 .msi 安装包，双击后自动装好了运行时，问题消失。

另一个坑是文件命名里的架构信息。windows-x86_64 表示 64 位，windows-i386 是 32 位。如果你在 64 位系统上装 32 位版，功能正常但性能差，而且某些插件（比如 Lua filter）会加载失败。下载页上通常有表格，别只看文件名。

用 PowerShell 验证下载完整性，而不是直接解压

下载完成后，我习惯先算哈希值。Pandoc 的下载页通常会在每个文件旁边给出 SHA-256 校验值。我的做法是：

# 在 PowerShell 中计算已下载文件的 SHA-256
Get-FileHash .\pandoc-3.1.11-windows-x86_64.zip -Algorithm SHA256

把输出的哈希值和下载页上标注的对比。如果不一致，说明文件在传输中损坏或镜像有问题。我第一次没做这步，结果解压时 pandoc.exe 损坏，运行时直接闪退。后来养成了习惯，每次下载都先算哈希，虽然多花十秒，但省去了后续排查的半小时。

如果下载页没提供哈希值，我还有个备用方案：用 tar 测试压缩包完整性（Windows 10 自带）：

tar -tf .\pandoc-3.1.11-windows-x86_64.zip > $null
if ($LASTEXITCODE -eq 0) { "压缩包结构完整" } else { "压缩包可能损坏" }

tar -tf 只列出文件列表而不解压，如果中途报错，说明文件头或目录结构有问题。这个方法不验证内容，但能快速筛掉明显损坏的文件。

安装后立刻做“冒烟测试”，别等真正用时才发现问题

装完 Pandoc 后，我建议立刻在命令行跑一个最小转换，验证核心功能。不要直接跑大文件，先用一个一行的 Markdown 测试：

# 创建测试文件，转换后检查输出
echo "# 测试" > test.md
pandoc test.md -o test.docx
if (Test-Path test.docx) { "转换成功，文件大小: $((Get-Item test.docx).Length) 字节" }

如果这一步就失败，常见原因有三个：

PATH 环境变量没生效：安装 .msi 后，新开的 PowerShell 窗口才有新 PATH。如果你在旧窗口运行，会提示“找不到命令”。关掉重开即可。
杀毒软件拦截：Pandoc 的 exe 会被某些杀软误报，导致进程被终止。我遇到过 Windows Defender 在解压时把 pandoc.exe 隔离了，报“Trojan:Win32/Emotet”之类。这种时候去“病毒与威胁防护”的“保护历史记录”里恢复，并添加排除目录。
缺少默认输出目录：如果当前目录是只读位置（比如 C:\Program Files 下），写文件会失败。换到 C:\Users\你的用户名\Documents 再试。

冒烟测试通过后，我还会测试一次 PDF 输出。Pandoc 转 PDF 依赖 LaTeX 引擎（如 pdflatex 或 xelatex），这不是 Pandoc 自带的。如果你只装了 Pandoc，运行 pandoc test.md -o test.pdf 会报错“pdflatex not found”。下载页上通常有说明“PDF output requires a LaTeX engine”，但很多人忽略。我的解决方法是安装 MiKTeX（Windows 版），然后在 Pandoc 命令中指定引擎：

pandoc test.md -o test.pdf --pdf-engine=xelatex

版本差异：下载页上的“Latest”不一定适合你

Pandoc 下载页通常有“Stable release”和“Development builds”两个标签。我建议普通用户只下 Stable。有一次我贪新鲜下了 dev 版，结果一个 Lua filter 在新版本里 API 变了，脚本直接报错。回退到 stable 版本后一切正常。

另外，别只看主版本号。Pandoc 的版本号是三位（如 3.1.11），其中第三位是补丁版本。如果下载页显示 3.1.10 和 3.1.11，选 3.1.11 通常包含 bug 修复。但如果你在写自动化脚本，建议固定版本号，不要用“latest”下载链接，否则将来版本升级可能破坏脚本。

我的做法是：在下载页找到具体版本的文件，而不是用 pandoc-3.1.11-windows-x86_64.zip 这样的通用链接。这样我可以把版本号写进脚本，确保可重复。

一点说明

以上是我个人在 Windows 上使用 Pandoc 下载页的经验。不同操作系统（macOS、Linux）的下载页布局和依赖要求不同，而且 Pandoc 版本更新很快，具体细节可能变化。如果你在下载或安装时遇到我文中没提到的报错，欢迎在评论区补充你的场景和解决方案——尤其是那些在镜像站下载后出现的奇怪问题，大家一起排查会更快。

用 Pandoc 之前，先学会看下载页：一次真实的跨平台踩坑记录