Sublime Text 本身不渲染公式，也不管理文献；它只调用外部工具链完成编译、同步和预览。所谓“实时渲染”是误传，真正能做的是快速编译 + PDF 自动刷新 + 正向/反向跳转。
验证 latexmk 和 xelatex 是否真可用
所有后续配置失效的根源，90% 是这一步没过。Sublime 不会帮你装工具，只负责调用。
- 打开终端，运行
latexmk -v：必须输出类似Latexmk, John Collins, 29 May 2023. Version 4.79；若报command not found，说明没装或不在$PATH中 - 再运行
xelatex --version：中文论文必须用xelatex或lualatex，pdflatex默认不支持系统字体，硬上会炸出方块字 - Windows 用户装 MiKTeX 时务必勾选「Add MiKTeX to the system PATH」；macOS 用户用 MacTeX 后，路径通常是
/Library/TeX/texbin，但需确认该路径已写入 shell 配置（~/.zshrc或~/.bash_profile），且 Sublime 启动方式能读到——否则控制台里import os; print(os.environ.get('PATH'))看不到它
LaTeXTools 必须手动配 texpath 和 builder_settings
默认配置几乎必然失败：自动探测路径不可靠，pdflatex 引擎不兼容中文，script 构建器不支持 BibTeX 自动调度。
- 进
Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（别留空字段）：
{
"texpath": "/Library/TeX/texbin",
"builder": "latexmk",
"builder_settings": {
"cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "-quiet", "$file"],
"bibtex_tool": "biber"
},
"output_directory": "",
"view_pdf_viewer": "skim"
}
-
texpath必须精确到含可执行文件的目录，不是 TeX Live 安装根目录；多个路径用冒号分隔（macOS/Linux）或分号（Windows） -
-pdfxe强制走 XeLaTeX，绕过pdflatex的字体限制；-synctex=1是反向搜索（PDF 点击跳回源码）的前提，漏了就永远点不动 - 用
biber而非bibtex处理参考文献——现代中文论文基本都用biber支持 UTF-8 字段，bibtex会乱码
子文件第一行必须写 %!TEX root = main.tex
LaTeXTools 默认只把当前打开的文件当主文档。\input{ch1} 或 \include{refs} 的路径，是相对于 main.tex 所在目录计算的，不是子文件自身位置。
- 在
ch1.tex、refs.bib等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex - 不要写成
%!TEX root=main.tex（等号两边不能有空格）；不要写两行；不要放在注释块中间 - 如果主文件叫
paper.tex，那就写%!TEX root = paper.tex，名字必须完全一致，包括大小写和扩展名 - 不加这行，编译时会报
File `ch1.tex' not found，因为插件试图以子文件为起点去解析\input，路径全错
PDF 查看器必须匹配且启用 SyncTeX
编译成功但 PDF 不弹窗、点击无反应、跳转错行——问题 100% 出在查看器绑定或 SyncTeX 配置上，不是 Sublime 插件坏了。
- macOS 必用
Skim，别用 Preview.app（它根本不支持反向搜索）；安装后进Skim → Preferences → Sync，勾选Enable SyncTeX，并设PDF viewer为Sublime Text - Windows 必用
SumatraPDF，安装后进Settings → Options → Set inverse search command line，填："C:\Program Files\Sublime Text 3\sublime_text.exe" "%f:%l"（路径按你实际安装位置改） - Linux 用户可用
okular或evince，但必须确认它们启用了 D-Bus 支持；evince默认不支持反向搜索，得换okular --unique并在 LaTeXTools 配置中设"view_pdf_viewer": "okular" -
.synctex.gz文件必须和 PDF 在同一目录、同名；如果用了\includeonly{}或把 PDF 输出到output/子目录，SyncTeX 就会失效
最容易被忽略的一点：所有配置改完后，必须重启 Sublime Text，否则插件可能仍读取旧环境变量或缓存路径。控制台里 import os; print(os.environ.get('PATH')) 输出不包含 texbin，那一切设置都是白搭。
