Sublime Text 编译 LaTeX 失败主因是系统未识别 latexmk/xelatex，须先终端验证命令可用性；再手动配置 tex_path、禁用 use_simple_detection、设 builder 为 latexmk、子文件首行声明 %!TEX root = main.tex、构建命令含 -pdfxe 和 -synctex=1、选用匹配 PDF 查看器并从终端启动 Sublime。

Sublime Text 本身不编译 LaTeX，所有“编译失败”“空白 PDF”“点不动 SyncTeX”的问题，90% 都出在 latexmk 或 xelatex 命令根本没被系统识别——插件再配得花里胡哨，也调不动不存在的程序。

验证 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：
  • Windows 用户重装 MiKTeX，安装向导中务必勾选「Add MiKTeX to the system PATH」
  • macOS 用户用 MacTeX 后，确认 /Library/TeX/texbin 已写入 ~/.zshrc（不是 .bash_profile），并执行 source ~/.zshrc
  • Linux 用户常见坑是只装了 texlive-latex-recommended，它不含 latexmk，得补装：sudo apt install latexmk
• 装完必须重启 Sublime Text，否则它读不到新 PATH

手动写死 tex_path，禁用 use_simple_detection

LaTeXTools 的自动路径探测在多 TeX 版本、自定义路径、macOS 空格路径等场景下 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
• 同时指定构建器："builder": "latexmk"（别用 simple，它不调度 BibTeX/Biber）

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

LaTeXTools 不会自动推断主文档。你在 ch1.tex 里按 Ctrl+B，插件默认把它当主文件编译——input{refs.bib} 找不到，include{appendix} 报错，synctex 生成位置错乱，全因这行缺失。

• 在 ch1.tex、refs.bib 等所有子文件顶部，第一行且仅一行 写：%!TEX root = main.tex
• 不要写成 %!TEX root=main.tex（等号两边不能有空格）
• 不要写两行；不要放在注释块中间
• input{...} 和 include{...} 的路径，是相对于 main.tex 所在目录计算的，不是子文件自身位置

编译命令必须带 -pdfxe 和 -synctex=1

漏掉任一参数，中文就炸方块、反向搜索就永远点不动。

• 在用户配置中补全 builder_settings：

  {
    "builder": "latexmk",
    "builder_settings": {
      "cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "-quiet", "$file"],
      "bibtex_tool": "biber"
    }
  }

• -pdfxe 强制走 xelatex，绕过 pdflatex 的字体限制；-synctex=1 是反向搜索（PDF 点击跳回源码）的前提
• 用 biber 而非 bibtex 处理参考文献——现代中文论文基本都用 biber 支持 UTF-8；bibtex 会乱码
• PDF 查看器须匹配：macOS 用 Skim（需在 Skim → Preferences → Sync 中启用 SyncTeX 并设 PDF viewer 为 Sublime Text）；Windows 用 SumatraPDF；Linux 用户得手动指定 evince 或 okular，且确保 D-Bus 支持开启

最常被忽略的是：Sublime 启动方式影响它读取的 PATH 环境变量，即使终端里 which latexmk 成功，从桌面图标启动的 Sublime 仍可能找不到命令——建议始终从终端用 subl 命令启动编辑器，确保环境一致。