编译失败主因是latexmk或xelatex未正确安装及路径配置错误，或子文件缺失%!TEX root = main.tex声明；需在终端运行latexmk -v和xelatex --version验证版本，PATH未配置则报command not found，Sublime仅调用系统命令不自动安装工具。
编译失败不是 Sublime 或插件坏了，90% 是 latexmk 找不到、xelatex 路径不对，或者子文件没写 %!TEX root = main.tex —— 这三件事没做对，按 Ctrl+B 永远只生成空白 PDF 或报 command not found。
怎么验证 latexmk 和 xelatex 真的可用
别跳过这步。Sublime 不会帮你装工具，它只调用你系统里已有的命令。
- 打开终端（macOS/Linux）或命令提示符（Windows），依次运行：
latexmk -v和xelatex --version - 两者都必须返回版本号；若报
command not found，说明 PATH 没配好 - macOS 用户装 MacTeX 后，常漏掉把
/Library/TeX/texbin加进 shell 的$PATH；可在终端执行echo $PATH确认 - Windows 用户装 MiKTeX 时没勾选「Add MiKTeX to the system PATH」，就得手动把类似
C:\Program Files\MiKTeX\miktex\bin\x64的路径加进系统环境变量 - Linux 用户用
apt install texlive-full通常自带latexmk，但某些精简镜像需补装：sudo apt install latexmk
LaTeXTools 配置里最关键的三个字段
进 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴配置时只保留必要项，删掉所有 "use_simple_detection": true 这类干扰字段。
-
"tex_path"：必须精确到含可执行文件的目录，比如 macOS 是/Library/TeX/texbin，Windows 是C:/texlive/2023/bin/win32；多个路径用冒号（macOS/Linux）或分号（Windows）分隔 -
"builder_settings"：显式指定引擎和参数，例如："cmd": ["latexmk", "-pdfxe", "-quiet", "-synctex=1", "-interaction=nonstopmode", "$file"]——-pdfxe强制走 XeLaTeX，-synctex=1是反向搜索前提 -
"output_directory"：设为"out"可避免生成文件污染源码目录；但注意 PDF 和.synctex.gz必须在**同一目录**，否则 SyncTeX 失效
子文件编译失败？第一行缺了这行注释
论文必然拆成 main.tex + ch1.tex + refs.bib，LaTeXTools 默认以当前打开文件为主文档，\include{} 和 \bibliography{} 全部失效。
- 在每个子文件（如
ch1.tex）的**第一行且只能有一行**，写入：%!TEX root = main.tex - 路径要相对准确：如果
ch1.tex和main.tex同级，就写main.tex；如果main.tex在上层，写../main.tex - 路径含中文、空格或特殊字符时，
latexmk极易崩溃；整个项目路径建议全用英文、无空格 - 不加这行，你在
ch1.tex里按 Ctrl+B，实际编译的是ch1.tex单独文件，自然找不到导言区、参考文献和宏包
PDF 打不开、点不动、跳错行？SyncTeX 没真生效
不是插件问题，是生成环节或查看器没对齐。
-
-synctex=1参数必须出现在编译命令里（LaTeXTools 默认已加，但自定义builder时容易漏） - macOS 必须用 Skim，不能用 Preview.app；Skim 中需开启
Preferences → Sync → Enable SyncTeX，并设 PDF viewer 为 Sublime Text - Windows 推荐 SumatraPDF，Linux 用户若用 evince 或 okular，得确认 D-Bus 支持已启用
- 如果用了
\includeonly{}或多主文档结构，.synctex.gz只认主文件名；别把 PDF 输出到out/子目录，否则跳转必然失败
最常被忽略的其实是项目路径和字体链：路径带空格导致编译中断，中文字体没显式指定导致 ctex 报 No available font found——这些错误不会直接说“路径错了”，而是表现为 PDF 空白或乱码，得倒回去查终端输出和 .log 文件。
