latexmk和xelatex必须在终端直接运行成功，否则sublime编译必失败；需用latexmk -v和xelatex --version验证，path配置正确后重启编辑器，并在latextools设置中显式指定tex_path、-pdfxe、-synctex=1及%!tex root注释。
latexmk 和 xelatex 必须在终端能直接运行，否则 Sublime 里按 Ctrl+B 一定失败——插件不负责装工具，只负责调用。
验证 latexmk 和 xelatex 是否真可用
所有编译失败、空白 PDF、SyncTeX 点不动的问题，90% 源于这两个命令根本没被系统识别。
打开终端（macOS/Linux）或命令提示符（Windows），逐条执行：
-
latexmk -v：必须输出类似Latexmk, John Collins, 29 May 2023. Version 4.79；报command not found就说明没装或不在$PATH -
xelatex --version：中文论文必须用xelatex或lualatex；pdflatex默认不支持系统字体，硬上会出方块字 -
echo $PATH（macOS/Linux）或echo %PATH%（Windows）：确认上一步返回的路径确实在里面
常见修复方式：
- macOS 用户：重装
brew install --cask mactex，或手动把/Library/TeX/texbin加进~/.zshrc并执行source ~/.zshrc - Windows 用户：重装 MiKTeX，安装向导中务必勾选
Add MiKTeX to the system PATH - Linux 用户：补装
sudo apt install latexmk，再用which latexmk确认路径
装完必须重启 Sublime Text，否则它读不到新 PATH。
LaTeXTools 用户配置必须手动写死 tex_path 和 builder_settings
默认配置几乎必然失败：自动探测不可靠，pdflatex 引擎不兼容中文，script 构建器不调度 biber。
进 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（别留空字段）：
{
"tex_path": "/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"
}
关键点：
-
tex_path必须精确到含可执行文件的目录（如/Library/TeX/texbin），不是 TeX Live 安装根目录；多个路径用冒号分隔（macOS/Linux）或分号（Windows） -
-pdfxe强制走xelatex，绕过pdflatex的字体限制；漏了就炸方块字 -
-synctex=1是反向搜索（PDF 点击跳回源码）的前提；没这参数，Skim或SumatraPDF都点不动 -
bibtex_tool设为"biber"而非"bibtex"：现代中文参考文献基本都用biber支持 UTF-8；bibtex会乱码
子文件第一行必须写 %!TEX root = main.tex
论文不可能只一个 main.tex。你在 ch1.tex 里按 Ctrl+B，默认会被当主文档编译——\input{refs.bib} 找不到，\include{appendix} 报错，synctex 生成位置错乱。
解决方法非常具体：
- 在
ch1.tex、refs.bib、abstract.tex等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex - 等号两边不能有空格：
%!TEX root=main.tex是错的 - 不要写两行；不要放在注释块中间；不要缩进
- 路径是相对于子文件所在目录计算的，不是相对于项目根目录
这个注释是 LaTeXTools 定位主文档的唯一依据；没有它，多文件项目等于没配。
PDF 预览器必须匹配且启用 SyncTeX 支持
编译成功但 PDF 不弹窗、点不动反向搜索？不是插件坏了，是预览器没对上。
LaTeXTools 默认只认三款 SyncTeX 友好阅读器：
- macOS：必须用
Skim（Preview.app不支持反向搜索）；并在Skim → Preferences → Sync中勾选Enable SyncTeX，并设PDF viewer为Sublime Text - Windows：必须用
SumatraPDF（Adobe Reader不支持）；无需额外设置，只要路径正确即可 - Linux：可用
okular或zathura，但需确保启用 D-Bus 支持；evince原生不支持反向搜索
如果用了自定义 output_directory（比如 "output_directory": "build"），必须保证 main.pdf 和 main.synctex.gz 在同一目录下，且文件名完全一致——否则 SyncTeX 失效。
tex_path、%!TEX root、-synctex=1 这三个点，任何一个漏掉或写错，整个流程就会卡在某个环节不动，而且错误信息往往不直接指向根源。
