latexmk 和 xelatex 必须在终端直接可用，否则 Sublime Ctrl+B 必然失败；需验证版本、正确配置 tex_path、禁用 use_simple_detection、子文件首行加 %!TEX root、使用 -pdfxe 和 -synctex=1 构建、选用兼容 PDF 预览器并从终端启动 Sublime。
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
装完必须重启 Sublime Text，否则它读不到新 $PATH。
手动写死 tex_path，禁用 use_simple_detection
LaTeXTools 的自动路径探测在多 TeX 版本、自定义路径、含空格路径下 100% 失效。进 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（删掉所有注释和空行）：
- macOS（MacTeX）：
"tex_path": "/Library/TeX/texbin" - Windows（MiKTeX 2023）：
"tex_path": "C:\texlive\2023\bin\win32"（注意双反斜杠） - Linux（TeX Live）：
"tex_path": "/usr/local/texlive/2023/bin/x86_64-linux"
务必检查并删除配置中任何 "use_simple_detection": true 字段——它会覆盖你手动设的 tex_path。多个路径用冒号（macOS/Linux）或分号（Windows）分隔，例如 "/usr/texbin:/opt/texbin"。
子文件第一行必须加 %!TEX root = main.tex
论文项目必然拆成 main.tex + ch1.tex + refs.bib 等。Sublime 不会自动识别主文档。ch1.tex 里按 Ctrl+B 默认只编译它自己，include{}、ibliography{} 全部失效。
- 在
ch1.tex、appendix.tex等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex - 路径必须相对当前文件可解析（如
%!TEX root = ../main.tex也合法） - 整个项目路径不能含中文、空格或特殊字符
- 这行必须在文件最开头，前面不能有空行或 BOM
构建命令必须显式指定 -pdfxe 和 -synctex=1
默认配置走 pdflatex，中文会炸、数学符号漏字、参考文献不生成——这不是字体问题，是引擎不支持 UTF-8 和系统字体。
- 在用户配置中补全
builder_settings块，例如：
"builder_settings": {
"cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "$file"]
}
-
-pdfxe强制用 XeLaTeX 引擎，才能加载系统中文字体（如 Noto Sans CJK） -
-synctex=1是正向/反向搜索（SyncTeX）的前提，缺了就点不动 PDF 跳回源码 - 别用
simple构建器——它不调度 BibTeX/Biber，参考文献永远为空
最后，PDF 预览器必须选 Skim（macOS）、SumatraPDF（Windows）或 Evince（Linux），且要从终端启动 Sublime（尤其是 macOS），否则 SyncTeX 权限和进程通信会静默失败。
