sublime text 编译 latex 成功的前提是系统已正确安装并配置 latexmk 和 xelatex，需手动验证命令可用性；必须禁用自动路径探测、手动设置绝对 tex_path；构建器须设为 latexmk 并强制 -pdfxe 和 -synctex=1；子文件首行需声明 %!tex root = main.tex；pdf 查看器须支持 synctex（如 skim/sumatrapdf）。
Sublime Text 本身不编译 LaTeX，LaTeXTools 只是调用你系统里已装好的 latexmk 和 xelatex；如果终端里 latexmk --version 或 xelatex --version 报错，那 Ctrl+B 一定失败——配再细的插件也没用。
验证 latexmk 和 xelatex 是否真可用
这是所有配置的前提，跳过等于白忙。别信“我装过了”，必须亲手敲命令确认：
-
latexmk --version必须输出类似Latexmk, John Collins, 29 May 2023. Version 4.79；报command not found就说明没装或不在 PATH -
xelatex --version必须返回版本号；中文论文绝不能只靠pdflatex，它不加载系统字体，硬上必出方块字 - Windows 用户重装 MiKTeX 时务必勾选
Add MiKTeX to the system PATH；macOS 用户装完brew install --cask mactex后，要确认/Library/TeX/texbin已写入~/.zshrc并执行source ~/.zshrc - 装完必须重启 Sublime Text，否则它读不到新 PATH；可在 Sublime 控制台（
Ctrl+`）里输import os; print(os.environ.get('PATH'))检查
手动写死 tex_path，禁用 use_simple_detection
LaTeXTools 的自动路径探测在多 TeX 版本、空格路径、macOS 非标准安装等场景下 100% 失效。别留默认值，直接填绝对路径：
- macOS + MacTeX：
"tex_path": "/Library/TeX/texbin" - Windows + MiKTeX：
"tex_path": "C:\texlive\2023\binwin32"（注意双反斜杠） - Linux + TeX Live：
"tex_path": "/usr/local/texlive/2023/bin/x86_64-linux" - 配置中必须删掉任何
"use_simple_detection": true字段，它会覆盖你手动设的tex_path - 同时指定
"builder": "latexmk"，别用script构建器——它不调度biber，参考文献根本不会生成
强制用 xelatex 编译，加 -synctex=1 参数
默认走 pdflatex 是中文论文失败的主因：字体炸、数学符号漏、参考文献空白。必须改构建命令：
- 在
Preferences → Package Settings → LaTeXTools → Settings – User中，加入完整builder_settings：
"builder_settings": {
"cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "-quiet", "$file"],
"bibtex_tool": "biber"
}
-pdfxe 强制用 XeLaTeX，绕过 pdflatex + ctex 的字体探测陷阱-synctex=1 是反向搜索（PDF 点击跳回源码）的前提，漏了就永远点不动biber 而非 bibtex 处理参考文献，现代中文论文基本都依赖它支持 UTF-8 字段子文件第一行必须写 %!TEX root = main.tex
LaTeXTools 不会自动推断主文档。你在 ch1.tex 里按 Ctrl+B，默认把它当主文件编译——input{refs.bib} 找不到，include{appendix} 报错，synctex 位置全乱：
- 在
ch1.tex、refs.bib、appendix.tex等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex - 等号两边不能有空格，不能写成
%!TEX root=main.tex，也不能放在注释块中间 - 这个注释决定了
input{}和include{}的相对路径基准，也决定.synctex.gz文件名和生成位置
最常被忽略的是：PDF 查看器必须匹配且启用 SyncTeX 支持。Skim（macOS）、SumatraPDF（Windows）、Okular（Linux）可以，Preview.app 不行；即使命令全对，查看器没对上，反向搜索就永远失效。
