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"
- macOS（MacTeX）：
- 必须删掉配置里任何
"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 命令启动编辑器，确保环境一致。
