sublime text 需借助已安装的 pandoc 工具及 pandoc build system 插件实现 markdown 转 pdf；必须先配置 path 并验证 pandoc --version，再安装插件、设置构建系统，推荐用终端调试确保 xelatex 引擎与中文字体参数正确。
Sublime Text 本身不支持直接将 Markdown 转 PDF，必须借助外部工具 Pandoc，并通过插件桥接。核心前提是：你本地已安装 pandoc 命令行工具，否则任何插件都无效。
确认 pandoc 是否已正确安装并可用
这是最容易卡住的一步。很多用户装了 Pandoc 但没加进系统 PATH，导致 Sublime 找不到命令。
- 在终端（macOS/Linux）或命令提示符（Windows）中运行
pandoc --version，必须返回版本号（如pandoc 3.1.10） - 如果提示
'pandoc' is not recognized或command not found，说明未配置 PATH —— 不要跳过这步去装插件 - macOS 用户若用 Homebrew 安装，通常路径是
/opt/homebrew/bin/pandoc；Windows 用户需手动把 Pandoc 的bin目录（如C:UsersXXXAppDataLocalPandoc）加入系统环境变量
安装 Pandoc Build System 插件（推荐 Package Control 方式）
Sublime 上最轻量、维护良好的方案是 Pandoc Build System，不是“Pandoc”或“MarkdownPDF”这类容易过时或依赖 PhantomJS 的旧插件。
- 按下
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Package Control: Install Package - 搜索并安装
Pandoc Build System（作者是guillermooo，GitHub 仓库活跃） - 安装后无需重启，但需手动设置构建系统：菜单栏
Tools → Build System → Pandoc - 注意：该插件默认使用
pandoc命令，不自带二进制，完全依赖你本地安装的版本
用快捷键一键生成 PDF（并处理中文/样式问题）
默认构建会输出 .pdf，但中文乱码、无 CSS 样式、目录缺失是常见结果，需调整构建参数。
- 按下
Ctrl+Shift+B（或Cmd+Shift+B），选择Pandoc: PDF即可生成同名 PDF - 若中文显示为方块，必须添加 LaTeX 引擎和字体参数 —— 在 Sublime 中打开
Tools → Build System → New Build System…，填入：
{
"cmd": ["pandoc", "$file", "-o", "$file_base_name.pdf", "--pdf-engine=xelatex", "-V", "mainfont=PingFang SC", "--toc", "--toc-depth=3"],
"selector": "source.gfm",
"path": "/opt/homebrew/bin" // macOS 示例；Windows 改为你的 pandoc 所在目录，如 "C:\Users\XXX\AppData\Local\Pandoc"
}
-
--pdf-engine=xelatex是关键，支持 Unicode 和系统字体；-V mainfont=...指定中文字体（macOS 用PingFang SC，Windows 可试SimSun或Microsoft YaHei） - 保存为
Pandoc-ZH.sublime-build，之后在构建系统列表里就能选它
替代方案：不用插件，直接用终端调用 pandoc（更可控）
当插件行为异常（比如构建卡住、不报错也不出文件），直接甩开插件，用终端执行是最可靠的排障方式。
- 确保当前目录是 Markdown 文件所在路径，运行：
pandoc README.md -o output.pdf --pdf-engine=xelatex -V mainfont="PingFang SC" --toc
- 这样能立刻看到完整错误输出（比如缺少
xeCJK宏包、字体找不到），比插件隐藏的错误信息有用得多 - 一旦终端能成功生成，再回头检查 Sublime 的
path或构建参数 —— 90% 的“插件不工作”本质是路径或引擎配置偏差
真正麻烦的从来不是插件装不上，而是 Pandoc 的 PDF 输出链路太长：Markdown → AST → LaTeX → xelatex → PDF。中间任一环（字体、宏包、引擎路径）没对齐，就静默失败。建议先跑通终端命令，再套进 Sublime。
