latextools 在 sublime text 中成功编译需满足三要素：终端可直接运行 latexmk 和 xelatex、手动配置 tex_path 与 builder_settings 强制使用 xelatex、所有子文件首行声明 %!tex root = main.tex 且 pdf 查看器正确绑定。
latexmk 必须在终端里能直接运行，否则 Ctrl+B 一定失败——Sublime Text 不自带编译器，它只调用你系统里已装好的命令。
验证底层工具链是否就位
所有配置失效的起点，90% 是这一步没过。别跳过，别信“装完 MiKTeX/MacTeX 就自动好了”这种说法。
- 打开终端（macOS/Linux）或命令提示符（Windows），依次执行：
latexmk -v和xelatex --version - 两者都必须输出版本号；若报
command not found，说明没装、或装了但不在$PATH中 - macOS 用户装 MacTeX 后，路径通常是
/Library/TeX/texbin，需确认该路径已写入~/.zshrc（不是~/.bash_profile，除非你改过 shell） - Windows 用户装 MiKTeX 时，务必勾选「Add MiKTeX to the system PATH」；若已装却仍找不到，用
where latexmk查路径，再手动加进系统环境变量 - Linux 用户若用
apt install texlive-full，latexmk通常自带；但 Docker 镜像或精简安装常漏掉，需补装：sudo apt install latexmk biber
手动配 tex_path 和 builder_settings
默认配置几乎必然失败：自动探测不可靠，pdflatex 引擎不支持中文，script 构建器不调度 bibtex。
- 进
Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（别留空字段、别复制默认配置） -
tex_path必须精确到含可执行文件的目录，例如 macOS："tex_path":"/Library/TeX/texbin"；Windows："tex_path":"C:\texlive\2023\bin\win32"（双反斜杠或正斜杠均可，但路径不能含空格） -
"builder":"latexmk"是必须项，别用"builder":"script"或留空 -
builder_settings里强制走 XeLaTeX："cmd": ["latexmk","-pdfxe","-synctex=1","-interaction=nonstopmode","-quiet","$file"] - 参考文献必须用
biber（UTF-8 安全）："bibtex_tool":"biber"；若坚持用bibtex，得同步在导言区写ibliographystyle{unsrtd} - 删掉配置里任何
"use_simple_detection": true字段，它会覆盖你手动设的tex_path
子文件第一行必须写 %!TEX root = main.tex
多文件项目（main.tex + ch1.tex + refs.bib）里，LaTeXTools 默认只认当前打开文件为主文档，include{} 和 ibliography{} 全部失效。
- 在
ch1.tex、refs.bib等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex - 等号两边不能有空格：
%!TEX root=main.tex是错的 - 不能写两行，不能混在注释块里，不能缩进
-
main.tex路径必须是相对路径，且整个项目路径建议全英文、无空格、无中文——latexmk对特殊字符极其敏感
PDF 查看器绑定错，同步就失效
编译出 PDF 但不弹窗、点击 PDF 没反应、跳转不到源码——90% 是查看器没对上，不是插件 bug。
- macOS 必须用
Skim，不能用 Preview.app；Skim → Preferences → Sync → 勾选 “Enable SyncTeX”，并在 “PDF viewer” 下拉菜单选 “Sublime Text” - Windows 推荐
SumatraPDF，安装后配置"view_pdf_viewer":"sumatrapdf"；别用 Adobe Reader，它不支持 SyncTeX - Linux 可用
Evince或Zathura，但需确认其支持 SyncTeX 并已启用 - 配置项名是
view_pdf_viewer（不是viewer或pdf_viewer），值必须小写、无空格、严格匹配插件内置名称 - 如果 PDF 打开了但跳转无效，检查 Sublime 控制台（
Ctrl+`）是否有SyncTeX error或no viewer found类提示
latexmk 的调度逻辑和 %!TEX root 的解析规则，是整个流程里最容易被忽略的两个硬约束——它们不报错，但一错就静默失效。
