必须确保latexmk和xelatex在终端可直接运行，否则Sublime的Ctrl+B必失败；需验证版本、正确配置tex_path、子文件首行声明%!TEX root、显式指定-pdfxe和-synctex=1参数。
latexmk 必须在终端能直接运行，否则 Sublime 的 Ctrl+B 一定失败——这不是插件问题，是命令根本没通。
验证 latexmk 和 xelatex 是否真可用
跳过这步，后面所有配置都是白忙。打开终端（macOS/Linux）或 PowerShell（Windows），逐行执行：
-
latexmk -v—— 必须输出类似Latexmk, John Collins, 29 May 2023. Version 4.79 -
xelatex --version—— 必须返回版本号，不是command not found
任一失败，说明：
• macOS：重装 brew install --cask mactex，并确认 /Library/TeX/texbin 已写入 ~/.zshrc 且执行过 source ~/.zshrc
• Windows：重装 MiKTeX，安装时**必须勾选「Add MiKTeX to the system PATH」**
• Linux：补装 sudo apt install latexmk texlive-lang-chinese biber
手动写死 tex_path，禁用 use_simple_detection
LaTeXTools 默认的自动探测在多 TeX 版本、自定义路径、含空格路径下 100% 失效。进 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（删掉所有注释和空行）：
macOS（MacTeX）：{"tex_path":"/Library/TeX/texbin","builder":"latexmk"}
Windows（MiKTeX 2023）：{"tex_path":"C:\texlive\2023\binwin32","builder":"latexmk"}
Linux（TeX Live）：{"tex_path":"/usr/local/texlive/2023/bin/x86_64-linux","builder":"latexmk"}
务必检查并删除配置中任何 "use_simple_detection": true 字段——它会覆盖你手动设的 tex_path。
子文件第一行必须加 #!/TEX root = main.tex
论文必然拆成 main.tex + ch1.tex + refs.bib。Sublime 不会自动识别主文档，ch1.tex 里按 Ctrl+B 默认只编译它自己，include{} 和 ibliography{} 全部失效。
在 ch1.tex、refs.bib 等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex
注意：
• 路径必须相对当前文件可解析（如 ../main.tex 也合法）
• 整个项目路径不能含中文、空格或特殊字符
• 这行必须在文件最开头，前面不能有空行或 BOM
builder_settings 必须显式指定 -pdfxe 和 -synctex=1
默认配置走 pdflatex，中文会炸、数学符号漏字、参考文献不生成——这不是字体问题，是引擎不支持 UTF-8 和系统字体。
在用户配置中加入完整 builder_settings：
{
"builder": "latexmk",
"builder_settings": {
"cmd": ["latexmk", "-pdfxe", "-quiet", "-synctex=1", "-interaction=nonstopmode", "$file"],
"bibtex_tool": "biber"
}
}
说明：
• -pdfxe 强制用 XeLaTeX，绕过 pdflatex + ctex 的字体探测陷阱
• -synctex=1 是 PDF 点击跳回源码的前提，漏了就永远点不动
• 如果用 BibTeX（非 biber），把 "bibtex_tool": "biber" 换成 "bibtex_tool": "bibtex"，且导言区有 ibliographystyle{unsrt}
PDF 查看器绑定错，同步就彻底失效；路径含空格、subl 命令未从终端启动、main.tex 编码不是 UTF-8 —— 这些细节比语法本身更容易卡住整个流程。
