sublime text 本身不编译 latex，90% 编译失败源于 latexmk 或 xelatex 命令未被系统识别；必须先在终端验证 latexmk -v 和 xelatex --version，再手动配置 latextools 的 tex_path、command 及 %!tex root 注释，并选用 skim（macos）或 sumatrapdf（windows）等支持 synctex 的 pdf 阅读器。
Sublime Text 本身不编译 LaTeX，所有“编译失败”“空白 PDF”“反向搜索无效”问题，90% 都卡在 latexmk 或 xelatex 命令根本没被系统识别——不是插件配错了，是底层工具链没通。
终端先跑通 latexmk -v 和 xelatex --version
这是不可跳过的验证步骤。Sublime 的构建系统不继承 shell 的完整环境，但命令必须在终端里能直接执行，否则插件调用必失败。
- Windows 用户装 MiKTeX 后，安装向导中必须勾选「Add MiKTeX to the system PATH」；若已装完，重装或手动把
C: exlive3inwin32（路径按你实际年份/版本改）加进系统环境变量 - macOS 用户用 MacTeX，默认路径是
/Library/TeX/texbin，但需确认它真在$PATH里：终端执行echo $PATH，看输出是否含该路径；若没有，改~/.zshrc（不是.bash_profile）并source ~/.zshrc - Linux 用户常见坑是只装了
texlive-latex-recommended，它不含latexmk；必须补装：sudo apt install latexmk，再验证which latexmk是否返回有效路径
LaTeXTools 用户配置必须手动写死 tex_path 和 command
插件默认的 use_simple_detection 会扫描 PATH 却忽略你真实 bin 目录位置，尤其在多 TeX 版本、自定义安装路径、或 macOS 上极易失效。
- 打开 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴完整配置，不要留空字段
- Windows 示例（MiKTeX 2023）：
"tex_path": "C:\texlive\2023\bin\win32"（注意双反斜杠） - macOS 示例（MacTeX）：
"tex_path": "/Library/TeX/texbin"；若用 Homebrew 安装的 MacTeX，路径可能是/opt/homebrew/bin或/usr/local/bin，以which xelatex输出为准 - 必须显式指定引擎：
"command": ["xelatex"]或["lualatex"]；别依赖默认pdflatex，中文、Unicode、字体都会炸 - 删掉任何
"use_simple_detection": true字段——它会覆盖你手动设的tex_path
子文件第一行必须有 %!TEX root = main.tex
论文必然拆成 main.tex + ch1.tex + refs.bib，LaTeXTools 不会自动推断主文件。没有这行注释，input{ch1} 找不到上下文，参考文献不生成，synctex 也只认当前文件名。
- 这行必须且只能出现在子文件（如
ch1.tex）的**第一行**，前面不能有空行、空格或注释 - 路径写相对路径即可：
%!TEX root = ../main.tex也合法，但推荐扁平结构，都放在同一目录下 - 如果用了
includeonly{}，synctex.gz仍只绑定main.tex，PDF 和.synctex.gz必须同目录、同名
PDF 查看器必须支持 SyncTeX 且正确绑定
正向跳转（编译后自动打开 PDF 并定位）和反向搜索（PDF 里 Ctrl+Click 跳回源码）不是 Sublime 自带功能，全靠查看器配合。选错或没开权限，这两项就废了。
- macOS 必用 Skim，不是 Preview.app；Skim 中必须开启 Preferences → Sync → Enable SyncTeX，并设「PDF viewer」为 Sublime Text
- Windows 推荐 SumatraPDF；安装后无需额外设置，LaTeXTools 默认识别它；若用其他阅读器（如 Adobe Acrobat），反向搜索一定失效
- Linux 用户可用 Okular，但需确保启用 D-Bus 支持：
okular --unique启动；Evince 不稳定，慎用 - 配置里
"view_pdf_viewer": "skim"（macOS）或"view_pdf_viewer": "sumatra"（Windows）必须与实际安装一致，大小写敏感
最易被忽略的是：Sublime 启动方式影响环境变量读取——从 Dock 或 Finder 点开 Sublime，它可能完全读不到你在终端里配置的 $PATH 或字体环境；务必从终端执行 subl 启动，或重启系统让环境变量全局生效。
