latextools 不支持“实时渲染公式”，只调用系统命令编译并刷新 pdf；真正可落地的是保存即编译、pdf 自动刷新和 synctex 跳转。90% 的配置失败源于 latexmk 或 xelatex 未被正确调通，必须验证终端中二者版本可用、手动写死 tex_path、所有子文件首行严格标注 %!tex root = main.tex，并从终端启动 sublime 以确保 path 生效。
LaTeXTools 不支持“实时渲染公式”，它只调用系统命令编译并刷新 PDF。所谓“实时”是误传——真正可落地的是：保存即编译 + PDF 自动刷新 + 点击跳转源码行（SyncTeX）。所有公式空白、PDF 打不开、中文变方块、跳转失效，90% 都卡在 latexmk 或 xelatex 根本没被 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 - 确保
main.tex是你真正的主文件名，拼写和大小写必须完全一致 - 该行不能有空格、注释或空行在它前面；也不能出现在第二行
- 如果用了
subfiles宏包，仍需保留此声明，否则 SyncTeX 跳转会错位
选用支持 SyncTeX 的 PDF 查看器并从终端启动 Sublime
PDF 查看器不支持 SyncTeX，或 Sublime 没读到系统 PATH，就会导致点击 PDF 无法跳回源码。
- macOS 推荐
Skim，启用偏好设置 → 同步 → PDF-TeX 同步支持 → 选择Sublime Text - Windows 推荐
Sumatra PDF，无需额外配置，开箱即用 - Linux 可用
Evince（需启用 D-Bus 支持）或Zathura（配合zathura-pdf-mupdf插件） - 必须从终端启动 Sublime：
subl（macOS/Linux）或subl.exe（Windows），否则它继承不到 shell 的PATH - 不要双击图标启动，也不要通过桌面快捷方式——它们启动的进程环境变量不包含你刚配好的 TeX 路径
latexmk 能否执行、tex_path 是否写对、%!TEX root 是否每份子文件都写了且位置严格。这三个点全对了，其他问题基本迎刃而解。
