直接用pandoc生成pdf失败是因为它依赖外部latex引擎（如xelatex），需安装tex发行版并配置path；sublime需自定义build system指定--pdf-engine=xelatex和中文模板zh-template.latex。
为什么直接用 pandoc 命令行生成 PDF 会失败？
因为 pandoc 本身不渲染 PDF，它依赖外部 LaTeX 引擎（如 pdflatex 或 xelatex）完成排版。没装 TeX 发行版（如 TeX Live 或 MacTeX），或者 PATH 里找不到 pdflatex，就会报错 Could not find pandoc-citeproc or pdflatex 或类似提示。
实操建议：
- Windows 用户推荐安装
texlive-full（约 4GB），最小化安装容易缺字体或宏包，后续编译常卡在fontspec或ctex - macOS 用户用
brew install --cask mactex，别只装basic-tex，否则中文支持和常用宏包（如geometry、hyperref）会缺失 - Linux（Ubuntu/Debian）运行
sudo apt install texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra texlive-lang-chinese，漏掉texlive-lang-chinese会导致中文乱码或编译中断 - 验证是否就绪：终端执行
pdflatex --version和pandoc --version都应返回有效输出
Sublime Text 中怎么让 Build System 正确调用 pandoc？
默认 Build System 不知道你的 pandoc 路径，也不传 LaTeX 引擎参数，更不会处理中文路径或空格——直接选 “Pandoc” 构建几乎必失败。
实操建议：
- 新建 Build System（
Tools → Build System → New Build System），粘贴以下内容并保存为PandocLaTeX.sublime-build：
{
"cmd": ["pandoc", "-s", "--pdf-engine=xelatex", "-o", "$file_path/$file_base.pdf", "$file"],
"selector": "text.html.markdown",
"path": "/usr/local/bin:/opt/homebrew/bin",
"shell": true
}
说明：
-
--pdf-engine=xelatex是关键：比pdflatex更好支持 UTF-8 和系统字体，中文文档必须用它 -
"path"要填对：macOS 上可能是/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel）；Windows 需写成C:\Users\xxx\AppData\Local\Pandoc\;C:\texlive\2023\bin\win32\ -
"shell": true让 Sublime 走 shell 环境，否则 PATH 不生效，pdflatex找不到 - 文件必须是 Markdown（
.md），且 Sublime 当前语法设置为Markdown，否则selector不匹配
中文标题、目录、代码块在 PDF 里显示异常怎么办？
不是 Pandoc 配置问题，而是 LaTeX 模板缺中文支持层。默认模板用 article 类，不加载中文字体和 CJK 排版逻辑，结果标题变方框、目录空白、代码块断行错乱。
实操建议：
- 创建一个最小可用模板
zh-template.latex，内容只需包含：documentclass[12pt]{article}usepackage{ctex}usepackage{fvextra}DefineVerbatimFont{Highlighting}{UTF8}{bsr}{m}{n}
（ctex处理中文字体与章节，fvextra+Highlighting修复代码块换行） - 构建命令加参数：
pandoc -s --pdf-engine=xelatex --template=zh-template.latex -o out.pdf in.md - 若用 Sublime Build System，把
"cmd"改为：["pandoc", "-s", "--pdf-engine=xelatex", "--template=zh-template.latex", "-o", "$file_path/$file_base.pdf", "$file"] - 注意：模板路径是相对于当前打开的 Markdown 文件路径，不是 Sublime 安装目录
如何避免每次改完 Markdown 都手动按 Ctrl+B？
Sublime 的 on_save 自动构建不推荐直接绑定 pandoc，因为编译失败会弹出错误面板打断编辑流，且 PDF 生成慢（尤其含图或参考文献时），频繁触发反而拖慢。
实操建议：
- 用插件
AutoSetSyntax+ApplySyntax确保 .md 文件自动识别为 Markdown，否则 Build System 不触发 - 更稳的方式是设快捷键：打开
Preferences → Key Bindings，加一行：{"keys": ["ctrl+alt+p"], "command": "build", "args": {"select": false}} - 如果真要保存即构建，装插件
OnSaveBuild，但务必在插件设置里勾选"only_on_modified"并设置"extensions_to_build_on_save"为["md"]，否则 .gitignore 修改也会触发 PDF 编译 - PDF 生成后不自动打开：Sublime 默认不打开，但若你装了
SideBarEnhancements或自定义脚本，检查是否有open_file调用，删掉即可
最麻烦的其实是字体嵌入和页眉页脚定制，那得进 LaTeX 模板深调，Pandoc 层面基本没得绕。
