Pandoc 跨平台安装指南：从入门到源码编译

Pandoc 作为一款强大的文档格式转换工具，支持多种文档格式间的相互转换。本文将详细介绍在各种操作系统环境下安装 Pandoc 的方法，以及从源码编译的高级技巧。

一、基础安装方法

对于大多数用户而言，最简单的安装方式是使用官方提供的安装包。官方为不同操作系统提供了预编译的二进制包，这些包通常包含了 Pandoc 的所有必要组件。

Windows 系统安装

Windows 用户可以通过以下方式安装：

1. MSI 安装包：这是最推荐的方式，安装程序会自动处理路径配置和版本更新
2. ZIP 压缩包：适合高级用户，解压后需手动配置环境变量
3. 包管理器安装：
   • 使用 Chocolatey：choco install pandoc
   • 使用 Winget：winget install --source winget --exact --id JohnMacFarlane.Pandoc

macOS 系统安装

macOS 用户可选择：

1. PKG 安装包：图形化安装，简单易用
2. Homebrew 安装：brew install pandoc
3. MacPorts 安装：port install pandoc

Linux 系统安装

大多数 Linux 发行版的仓库中都包含 Pandoc：

1. 使用系统包管理器：

   • Debian/Ubuntu：apt-get install pandoc
   • Fedora：dnf install pandoc
   • Arch Linux：pacman -S pandoc

2. 手动安装 DEB/RPM 包：可从官方下载最新版本

二、高级安装选项

Conda 安装

通过 Conda 生态系统安装：

conda install -c conda-forge pandoc

此方法会安装静态链接的可执行文件，但需要注意其对 Lua 过滤器的限制。

Docker 方式

官方提供两种 Docker 镜像：

1. 基础镜像：仅包含 Pandoc
2. LaTeX 镜像：包含 Pandoc 和精简版 LaTeX

使用示例：

docker run --rm --volume "`pwd`:/data" --user `id -u`:`id -g` pandoc/latex input.md -o output.pdf

三、从源码编译安装

对于需要定制功能或使用开发版的用户，可以从源码编译安装。

准备工作

1. 获取源码：

   • 发布版源码包
   • Git 仓库克隆：git clone https://github.com/jgm/pandoc

2. 安装 Haskell 工具链：

   • GHC (Glasgow Haskell Compiler)
   • Cabal 或 Stack 构建工具

使用 Stack 构建

推荐方法，自动化程度高：

stack setup
stack install pandoc-cli

构建完成后，可执行文件会安装在 ~/.local/bin 目录下。

使用 Cabal 构建

更灵活的方法：

cabal update
cabal install pandoc-cli

自定义构建选项

可通过配置标志定制构建：

• embed_data_files：将数据文件嵌入二进制
• lua：启用 Lua 过滤器支持
• server：启用 HTTP 服务器模式

四、测试与验证

安装完成后，建议运行测试套件验证安装：

# 使用 Stack
stack test

# 使用 Cabal
cabal test

对于特定功能的测试：

cabal test --test-options='-p markdown'

五、PDF 输出支持

Pandoc 默认使用 LaTeX 生成 PDF，需要额外安装：

• Windows：MiKTeX
• macOS：BasicTeX 或 TinyTeX
• Linux：TeX Live

安装后可通过 --pdf-engine 选项指定不同的 PDF 引擎。

六、常见问题解决

1. Lua 过滤器限制：静态链接的二进制版本不支持依赖 C 模块的 Lua 过滤器，需从源码编译
2. 多版本冲突：避免使用多种安装方法导致版本冲突
3. 字体问题：PDF 生成时若提示字体缺失，需安装额外字体包

通过本文介绍的各种方法，用户可以根据自身需求选择最适合的 Pandoc 安装方式。对于大多数用户，推荐使用官方提供的二进制安装包；对于开发者或需要特定功能的用户，则可以考虑从源码编译安装。