Sublime中LaTeX编译失败主因是latexmk或xelatex未被系统识别；须在终端运行latexmk -v和xelatex --version验证，失败则重装TeX发行版并重启Sublime，再手动配置LaTeXTools的tex_path、禁用use_simple_detection、子文件首行声明%!TEX root = main.tex，并匹配Skim/SumatraPDF等支持SyncTeX的PDF查看器。

latexmk 和 xelatex 必须在终端能直接运行，否则 Sublime 里按 Ctrl+B 一定失败——不是插件问题，是命令根本调不动。

验证 latexmk 和 xelatex 是否真可用

这是所有配置的前提，跳过这步后续全白搭。

• 打开终端（macOS/Linux）或 CMD/PowerShell（Windows），运行：latexmk -v —— 必须输出类似 Latexmk, John Collins, 29 May 2023. Version 4.79 的版本信息
• 再运行：xelatex --version —— 中文论文必须用 xelatex 或 lualatex，pdflatex 默认不支持系统字体，硬上会出方块字
• 若任一命令报 command not found：
  • macOS：重装 brew install --cask mactex（BasicTeX 不含 latexmk）
  • Windows：重装 MiKTeX，安装向导中务必勾选「Add MiKTeX to the system PATH」
  • Linux：执行 sudo apt install latexmk，再确认 which latexmk 返回有效路径
• 装完必须重启 Sublime Text，否则它读不到新 PATH

LaTeXTools 配置必须手动写死 tex_path

默认的 use_simple_detection 在 MacTeX、多 TeX 版本、或 Sublime 从 Dock 启动时大概率失效——它扫描 PATH 却找不到你真实 bin 目录的位置。

• 进 Preferences → Package Settings → LaTeXTools → Settings – User
• 粘贴完整配置（删掉所有注释和空行），例如 macOS + MacTeX：

  {
    "tex_path": "/Library/TeX/texbin",
    "builder": "latexmk",
    "builder_settings": {
      "cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "-quiet", "$file"],
      "bibtex_tool": "biber"
    },
    "output_directory": "",
    "view_pdf_viewer": "skim"
  }

• tex_path 必须精确到含可执行文件的目录（如 /Library/TeX/texbin），不是 TeX Live 安装根目录；多个路径用冒号分隔（macOS/Linux）或分号（Windows）
• 显式指定 "cmd": ["latexmk", "-pdfxe", ...]：强制走 XeLaTeX，绕过 pdflatex 的字体限制；-synctex=1 是反向搜索（PDF 点击跳回源码）的前提，漏了就永远点不动
• 删掉任何 "use_simple_detection": true 字段——它会覆盖你手动设的 tex_path

子文件第一行必须加 %!TEX root = main.tex

LaTeXTools 默认只把当前打开的文件当主文档。\input{ch1} 或 \include{refs} 的路径，是相对于 main.tex 所在目录计算的，不是子文件自身位置。

• 在 ch1.tex、refs.bib 等所有子文件顶部，**第一行且仅一行**写：%!TEX root = main.tex
• 注意格式：= 两边不能有空格；不能写成 %!TEX root=main.tex；不能放在注释块中间；不能有两行
• 没有这行，input{refs.bib} 找不到上下文，参考文献不生成，synctex 只认当前文件名，跳转错乱

PDF 查看器必须支持 SyncTeX 且正确绑定

编译生成了 PDF 却不弹窗、点了没反应，几乎全是查看器没对上。

• macOS 必须用 Skim（Preview.app 不支持反向搜索），并在 Skim 的 Preferences → Sync 中：
  • 勾选 Enable SyncTeX
  • 设置 PDF viewer 为 Sublime Text
  • 勾选 Check for file changes
• Windows 推荐 SumatraPDF，Linux 可用 okular 或 zathura（需启用 D-Bus 支持）
• 别用 "view_pdf_viewer": "auto"——它在多数场景下识别不准，尤其跨平台启动时
• .pdf 和 .synctex.gz 必须在同一目录、同名；如果用了 \includeonly{} 或输出到 output/ 子目录，synctex 就会失效

最常被忽略的是 Sublime 启动方式和 shell 环境的割裂：你在终端里配好了 PATH，但 Sublime 从 Dock 或桌面图标启动时，可能根本读不到 ~/.zshrc 里的配置。这时候 import os; print(os.environ.get('PATH')) 在 Sublime 控制台（Ctrl+`）里输出的路径，才是它真正能用的。