前言
Pandoc 的 --pdf-engine 参数用于指定外部 PDF 生成引擎（Pandoc 自身不直接生成 PDF，需借助第三方引擎），核心分为「LaTeX 类引擎」（基于 TeX/LaTeX，支持复杂排版、公式、目录等）和「非 LaTeX 类引擎」（基于 HTML 转 PDF，无需 LaTeX 环境）两大类。以下是完整的支持列表、特点及适用场景。
核心说明
Pandoc 生成 PDF 有两条路径：
- LaTeX 路径（默认）：先将源文件转为 LaTeX 中间文件，再调用 LaTeX 引擎生成 PDF（支持复杂排版、公式、目录、交叉引用）；
- HTML 路径：先将源文件转为 HTML，再调用 HTML 转 PDF 引擎生成 PDF（无需 LaTeX 环境，适合简单文档 / HTML 源文件）。
可通过 pandoc --list-pdf-engines 查看当前版本支持的所有引擎（不同 Pandoc 版本支持范围略有差异，新版会新增 / 弃用部分引擎）。
LaTeX 类引擎（推荐复杂排版 / 中文场景）
这类引擎依赖 TeX/LaTeX 环境（如 TeX Live、MikTeX），支持 Pandoc 所有高级排版特性（公式、目录、图片列表等），是中文 PDF 转换的核心选择。
| 引擎名称 | 核心特点 | 适用场景 | 示例命令 |
|---|---|---|---|
| pdflatex | 1.经典 LaTeX 引擎（Pandoc 默认）； 2.不支持原生 Unicode，中文需依赖 CJK 宏包（配置复杂）；3.兼容性最好，宏包生态最完善。 | 无中文的英文文档、简单排版场景；不推荐中文场景（配置繁琐易出错）。 | pandoc input.md -o output.pdf --pdf-engine=pdflatex |
| xelatex | 1. 基于 XeTeX，原生支持 Unicode + 系统字体（中文 PDF 首选）；2.无需复杂宏包，直接指定中文字体即可；3.容器化需安装 texlive-xetex + 中文字体。 | 中文文档、含复杂公式 / 排版的文档；Docker/Alpine 环境优先选。 | pandoc input.md -o output.pdf --pdf-engine=xelatex --variable mainfont=“WenQuanYi Zen Hei” |
| lualatex | 1. 基于 LuaTeX，支持 Unicode + 系统字体（中文支持略逊于 xelatex）；2.内置 Lua 脚本引擎，可自定义排版逻辑；3. 宏包兼容性稍弱于 xelatex。 | 需 Lua 脚本扩展排版逻辑的场景；中文场景可作为 xelatex 的备选。 | pandoc input.md -o output.pdf --pdf-engine=lualatex --variable mainfont=“SimSun” |
| latexmk | 1. 不是独立引擎，是 LaTeX 编译脚本；2. 自动处理「多次编译」（如目录、交叉引用需多次编译生效）；3. 底层调用 pdflatex/xelatex 等。 | 复杂长文档（如论文、手册），含目录 / 交叉引用 / 公式，避免手动多次编译。 | pandoc input.md -o output.pdf --pdf-engine=latexmk --pdf-engine-opt=“-xelatex”（指定底层用 xelatex） |
| tectonic | 1. 现代轻量 LaTeX 引擎，自带宏包（无需系统 TeX 环境）；2. 体积小，适合容器化（Alpine 镜像可精简）；3. 中文支持需配置 Unicode 字体。 | 极简容器环境（不想装完整 TeX Live）、轻量中文文档；宏包支持不如 xelatex 全。 | pandoc input.md -o output.pdf --pdf-engine=tectonic |
| luatex/xetex | 纯 TeX 引擎（非 LaTeX），直接处理 TeX 源码，不加载 LaTeX 宏包；极少直接使用。 | 纯 TeX 文档转换（非 LaTeX），普通用户无需关注。 | 几乎不用，仅 TeX 开发者场景。 |
非 LaTeX 类引擎（推荐简单 HTML 转 PDF / 无 LaTeX 环境）
这类引擎无需 LaTeX 环境，Pandoc 先将源文件转为 HTML，再调用引擎生成 PDF，适合简单文档、HTML 源文件，或无法安装 TeX 环境的场景。
| 引擎名称 | 核心特点 | 适用场景 | 示例命令 |
|---|---|---|---|
| wkhtmltopdf | 1. 基于 WebKit 浏览器内核，HTML/CSS/JS 转 PDF；2. 支持网页渲染特性（如浮动、动画）；3. 排版精度一般，复杂表格 / 公式易错位。 | HTML 源文件转 PDF、简单文档（无复杂公式 / 目录）；无法安装 TeX 环境的场景。 | pandoc input.html -o output.pdf --pdf-engine=wkhtmltopdf |
| weasyprint | 1. Python 编写的 HTML/CSS 转 PDF 引擎；2. CSS 标准兼容性优于 wkhtmltopdf，排版更精准；3. 轻量，无浏览器依赖。 | 需精准 CSS 排版的 HTML 转 PDF 场景；比 wkhtmltopdf 更推荐的轻量选择。 | pandoc input.md -o output.pdf --pdf-engine=weasyprint |
| prince | 1. 商业级 HTML/CSS 转 PDF 引擎，排版效果极佳（接近专业出版）；2. 支持复杂布局、分页、跨页表格；3. 需授权（有试用版）。 | 商业级文档（如财报、手册），追求极致排版；成本较高，非开源免费。 | pandoc input.md -o output.pdf --pdf-engine=prince |
| context | ConTeXt 排版系统引擎（类似 LaTeX），支持 Unicode，学习成本高；极少使用。 | ConTeXt 文档转换，普通用户无需关注。 | 几乎不用，仅 ConTeXt 开发者场景。 |
| pdfroff | 基于 groff 排版系统，处理 roff/troff 文档转 PDF；极小众场景。 | 老旧 Unix 文档（roff 格式）转换，普通用户无需关注。 | 几乎不用。 |
xelatex
XeTeX 是支持 Unicode 字符集 和 原生系统字体 的 TeX 排版引擎（xelatex 是基于 XeTeX 的 LaTeX 编译器，Pandoc 生成中文 PDF 时核心依赖它）。它解决了传统 TeX 引擎对中文 / 非拉丁字符支持差的问题，以下是其命令行参数的 分类详解，重点标注和「Pandoc 转换中文 PDF」相关的核心参数：
核心执行模式与交互控制（自动化场景重点）
| 参数 | 作用 & 说明 | 示例 & 适用场景 |
|---|---|---|
| -interaction=STRING | 设置错误交互模式（核心！自动化 / 容器化必配）-batchmode：批量模式，无交互，忽略非致命错误继续执行；- nonstopmode：非停止模式，遇错不暂停（不等待用户输入），Pandoc 调用默认用此模式；- scrollmode：遇错暂停，按回车继续；- errorstopmode：默认，遇错暂停等待用户确认（自动化场景需避免）。 | xetex -interaction=nonstopmode test.tex；Pandoc 传递：pandoc input.md -o output.pdf --pdf-engine=xelatex --pdf-engine-opt=“-interaction=nonstopmode” |
| -halt-on-error | 遇到第一个错误立即停止处理（而非继续执行） | xetex -halt-on-error test.tex；适用：严格校验文档，避免生成不完整 PDF |
| 无参数基础调用 | xetex test.tex：编译 test.tex，默认生成 test.pdf（自动调用 xdvipdfmx 转换 XDV 为 PDF） | 最基础用法，Pandoc 底层会自动拼接类似命令 |
错误与调试辅助（排查问题必备）
| 参数 | 作用 & 说明 | 示例 & 适用场景 |
|---|---|---|
| [-no]-file-line-error | 禁用 / 启用「文件：行号：错误」样式的报错（默认启用） | xetex -no-file-line-error test.tex（仅显示错误内容，不显示行号，适合批量脚本）；xetex -file-line-error test.tex（调试时显示具体错误行，排查语法 / 字体问题） |
| -kpathsea-debug=NUMBER | 按 NUMBER 二进制位开启路径搜索调试（核心！排查「字体 / 宏包缺失」）NUMBER=1：显示 XeTeX 查找字体 / 宏包的完整路径 | xetex -kpathsea-debug=1 test.tex；适用：容器化环境中排查「找不到中文字体」「宏包缺失」问题 |
| -recorder | 生成 .fls 文件，记录编译过程中「读取 / 写入的所有文件路径」 | xetex -recorder test.tex（生成 test.fls，查看依赖的字体 / 宏包文件） |
| -src-specials[=WHERE] | 在 XDV 中间文件插入源文件标记，支持 PDF 预览器（如 VSCode/TeXstudio）和源文件双向跳转；WHERE：指定标记位置（math/par/hbox 等，逗号分隔） | xetex -src-specials=math,par test.tex |
| -synctex=NUMBER | 生成 SyncTeX 数据（PDF ↔ 源文件双向跳转）NUMBER=1 启用，0 禁用（Pandoc 默认启用） | xetex -synctex=1 test.tex（生成 test.synctex.gz，支持阅读器跳转到源行） |
文件 / 路径与输出控制（容器化场景重点）
| 参数 | 作用 & 说明 | 示例 & 适用场景 |
|---|---|---|
| -output-directory=DIR | 指定输出文件目录（PDF/LOG/AUX 等都放入 DIR，需提前创建） | xetex -output-directory=./output test.tex（输出 output/test.pdf）；Pandoc 传递：pandoc input.md -o output.pdf --pdf-engine=xelatex --pdf-engine-opt=“-output-directory=./output” |
| -jobname=STRING | 自定义「作业名」（替代输入文件名作为输出前缀） | xetex -jobname=report test.tex（编译 test.tex 生成 report.pdf，而非 test.pdf） |
| -papersize=STRING | 设置 PDF 页面尺寸（支持标准尺寸 a4/letter/a3，或自定义 100mm×200mm） | xetex -papersize=a4 test.tex；Pandoc 传递：pandoc input.md -o output.pdf --pdf-engine=xelatex --pdf-engine-opt=“-papersize=a4” |
| -no-pdf | 只生成 XDV 中间文件（不自动转 PDF），需手动调用 xdvipdfmx 转换 | xetex -no-pdf test.tex（生成 test.xdv，适合手动优化中间文件） |
| -output-driver=CMD | 指定 XDV 转 PDF 的驱动（替代默认的 xdvipdfmx） | 极少用，xdvipdfmx 是 XeTeX 最佳默认驱动 |
| -output-comment=STRING | 用自定义字符串替换 XDV 文件的默认注释（默认是当前日期） | 仅影响中间文件，对最终 PDF 无实质作用 |
功能扩展与安全控制
| 参数 | 作用 & 说明 | 示例 & 适用场景 |
|---|---|---|
| -etex | 启用 e-TeX 扩展（增加宏包 / 语法支持，xelatex 默认启用，无需手动指定） | xetex -etex test.tex |
| -mltex | 启用 MLTeX 扩展（旧版多语言支持，现代中文排版无需使用） | 几乎不用 |
| [-no]-shell-escape | 禁用 / 启用 \write18{SHELL命令}（允许 TeX 执行系统命令）;-默认禁用（安全）；- 启用后可调用外部工具（如生成图表、转换图片） | xetex -shell-escape test.tex;Pandoc 传递（需执行外部命令时）：pandoc input.md -o output.pdf --pdf-engine=xelatex --pdf-engine-opt=“-shell-escape” |
| -shell-restricted | 启用「受限版」\write18：仅允许执行预定义的安全命令（如 xdvipdfmx） | 比 -shell-escape 安全，适合需有限外部命令的场景 |
| [-no]-mktex=FMT | 禁用 / 启用自动生成缺失的 TeX/TFM 文件（FMT=tex/tfm）默认启用，容器化环境若依赖缺失可禁用 | xetex -no-mktex=tex test.tex |
| -8bit | 使所有字符可打印，不使用 ^^X 转义序列（XeTeX 原生支持 Unicode，无需手动指定） | 兼容旧版 8 位编码文档时用 |
配置与格式控制（高级 / 定制场景）
| 参数 | 作用 & 说明 | 示例 & 适用场景 |
|---|---|---|
| -cnf-line=STRING | 临时解析单行配置（替代 texmf.cnf 全局配置） | xetex -cnf-line=“TEXMFVAR=/tmp/texmf” test.tex适用：容器化环境临时修改 TeX 路径，无需改全局配置 |
| -fmt=FMTNAME | 使用指定的 .fmt 格式文件（预编译的 TeX 格式，如 xelatex.fmt） | xetex -fmt=xelatex test.tex（手动指定 xelatex 格式，xelatex 命令默认用此） |
| -ini | 以 xeinitex 模式运行（用于生成 .fmt 格式文件） | 仅 TeX 格式开发者使用，普通用户无需关注 |
| [-no]-parse-first-line | 禁用 / 启用解析输入文件第一行（若第一行是 %&fmtname，自动加载指定格式） | 默认启用，无需修改 |
| -translate-file=TCXNAME | 忽略该参数（XeTeX 原生支持 Unicode，无需 TCX 字符转换文件） | 兼容旧版 TeX 时的残留参数 |
帮助与版本
| 参数 | 作用 & 说明 | 示例 |
|---|---|---|
| -help | 显示帮助信息并退出 | xetex --help |
| -version | 输出版本信息并退出（验证容器中是否安装成功） | xetex --version |
补充：容器化安装引擎注意事项
xelatex：Alpine 需安装 texlive-full 或 texlive-xetex + font-wqy-microhei（中文字体）；
weasyprint：Alpine 需安装 python3-weasyprint；
wkhtmltopdf：Alpine 直接 apk add wkhtmltopdf 即可。
)
)
