sublime text 导出 pdf 实际依赖 pandoc + lualatex 链路，90% 问题源于 pandoc 或字体路径/配置错误；需确认绝对路径、source.gfm 语法、lualatex 引擎与中文字体严格匹配。
Sublime Text 本身不导出 PDF，所谓“学术级导出”实际是靠 pandoc + lualatex 链路完成的；菜单里 Export to PDF 灰掉、生成乱码、报 command not found，90% 是因为 pandoc 或字体没对上，不是 Sublime 设置错了。
确认 pandoc 和 lualatex 已安装且可被调用
Sublime 不继承你的 shell 环境变量，它只查自己知道的 PATH。即使终端里 pandoc --version 和 lualatex --version 都能跑，Sublime 仍可能找不到它们。
- Mac 用户：brew 安装后真实路径通常是
/opt/homebrew/bin/pandoc（Apple Silicon）或/usr/local/bin/pandoc（Intel），which pandoc可确认 - Windows 用户：安装时务必勾选「Add to system PATH」；若没勾，手动把
C:\Program Files\Pandoc\加进系统环境变量 - LaTeX 引擎必须匹配：用
lualatex就别配xelatex，否则--pdf-engine=lualatex参数会静默失败 - 验证方式：在 Sublime 的
Tools → Command Palette → Show Console里输入import os; os.environ.get("PATH")，看输出是否含你的pandoc目录
语法必须设为 source.gfm 才触发构建
Sublime 的构建系统靠 selector 字段匹配文件类型，不是靠后缀名。哪怕你打开的是 report.md，只要右下角没显示 “GitHub Flavored Markdown”，Ctrl+B 就不会走你写的 .sublime-build。
- 右键 → Set Syntax → Markdown (GFM)（不是 “Markdown” 或 “Plain Text”）
- 检查右下角状态栏，确认显示为
source.gfm；若显示text.html.markdown或其他，说明没生效 -
selector字段必须严格写成"selector": "source.gfm"，多一个空格或引号不闭合都会让构建失效
自定义 .sublime-build 必须填全路径和字体参数
用插件设置改 pdf_converter 不如直接写 .sublime-build 透明可控——尤其对中文排版，漏掉任何一个关键字段都会导致 PDF 崩坏。
-
"cmd"中的pandoc必须是绝对路径，比如"/opt/homebrew/bin/pandoc"；只写"pandoc"就会报command not found -
-V mainfont=Noto Sans CJK SC不能省：macOS/Linux 推荐该字体，Windows 可换为SimSun或Microsoft YaHei -
"path"字段要列全所有可能 bin 目录，用英文冒号分隔："/opt/homebrew/bin:/usr/local/bin:/usr/bin" - 确保字体已安装：
fc-list | grep "Noto"（Linux/macOS）或打开 macOS 字体册搜索Noto Sans CJK SC
中文 PDF 排版崩了？先查字体和引擎是否对齐
PDF 里中文变方块、段落挤成一团、目录不生成，几乎全是 mainfont 声明缺失或字体未安装导致的，跟 Sublime 关系不大。
-
lualatex不会 fallback 到系统默认中文字体，必须显式指定；-V mainfont=后面的字体名要和fc-list输出完全一致（空格、大小写都不能错） - 如果用了
SimSun却在 Windows 上没装对应字体（比如精简版系统），pandoc可能静默失败，PDF 文件为空或只有几页空白 - 数学公式、目录、页眉页脚等学术功能依赖 LaTeX 模板，默认模板不支持中文；加
-V documentclass=ctexrep或用自定义模板更稳妥 - 不要碰已废弃的
MarkdownPDF插件——它硬编码调用phantomjs，2026 年起彻底失效
真正卡住人的从来不是配置步骤多，而是某个路径少了一个斜杠、字体名多了一个空格、或者误以为 Sublime 自带 PDF 渲染能力。每一步都得在终端和 Sublime 里双重验证，而不是只信“看起来像对了”。
