sublime text 需手动配置 latex 工具链：验证 latexmk/xelatex 可用、写死 tex_path、禁用 use_simple_detection、子文件首行声明 %!tex root = main.tex、builder_settings 含 -pdfxe 和 -synctex=1、选用支持 synctex 的 pdf 查看器，并从终端启动 sublime 以确保 path 生效。
Sublime Text 本身不渲染公式，也不执行编译——它只调用你系统里装好的 latexmk、xelatex 或 lualatex。所谓“实时渲染公式”是常见误解；真正能落地的是：保存即编译 + PDF 自动刷新 + 点击 PDF 跳回源码行（SyncTeX）。所有公式显示为空白、PDF 打不开、跳转失效、中文变方块，90% 都卡在底层命令根本没被 Sublime 正确调通。
验证 latexmk 和 xelatex 是否真在终端可用
这是配置前必须亲手敲一遍的步骤，跳过等于白配。
- 打开终端（macOS/Linux）或 PowerShell（Windows），依次运行：
latexmk -v和xelatex --version - 两者都必须输出版本信息；若报
command not found，说明工具未安装或不在$PATH - 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，插件默认把它当主文件编译——include{}、ibliography{} 全部失效。
- 在
ch1.tex、refs.bib等所有子文件顶部，第一行且仅一行 写：%!TEX root = main.tex - 等号两边不能有空格；不能写成
%!TEX root=main.tex；不能放在注释块中间 -
main.tex必须与子文件在同一目录，或使用相对路径（如../main.tex） - 整个项目路径建议全用英文、无空格；含中文或空格时，
latexmk极易失败
builder_settings 里必须带 -synctex=1 和 -pdfxe
缺 -synctex=1，反向跳转（PDF 点击跳回源码）永远点不动；不用 -pdfxe，中文和数学字体大概率炸成方块。
- 在
Settings – User中补全builder_settings块："builder_settings": { "cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "-quiet", "$file"] } -
-pdfxe强制走 XeLaTeX 引擎，绕过pdflatex的字体限制；-synctex=1是 SyncTeX 的开关，漏了就废 - 如果用 Biber 管理参考文献，加一项：
"bibtex_tool": "biber"（bibtex会乱码 UTF-8 文献） - PDF 查看器要选支持 SyncTeX 的：Windows 用
sumatra，macOS 用skim，Linux 用okular；系统自带预览器（如 macOS Preview）不支持反向跳转
最常被忽略的是：Sublime 启动方式影响它能否读到 shell 的 PATH。直接双击图标启动的 Sublime，可能完全看不到你写进 ~/.zshrc 的 /Library/TeX/texbin——这时候哪怕终端里 which xelatex 能返回路径，Sublime 控制台里 import os; print(os.environ.get('PATH')) 也为空。解决办法只有两个：从终端用 subl 命令启动，或者把 tex_path 写死到配置里并彻底禁用自动探测。
