Sublime Text 本身不渲染公式也不编译 LaTeX，仅调用系统工具链实现快速编译、PDF 自动刷新及正向/反向跳转；90% 问题源于 latexmk/xelatex 未正确安装或 PATH 未生效，须手动验证命令可用性、写死 tex_path、禁用自动探测、子文件首行标注 %!TEX root = main.tex，并绑定 SyncTeX 支持的 PDF 查看器。
Sublime Text 本身不渲染公式，也不编译 LaTeX——它只调用你系统里装好的 latexmk、xelatex 或 biber。所谓“实时渲染”是误解，真正能落地的是：快速编译 + PDF 自动刷新 + 正向/反向跳转。所有卡顿、空白 PDF、点不动 SyncTeX、中文变方块的问题，90% 都出在底层命令根本没被 Sublime 调通。
验证 latexmk 和 xelatex 是否真在终端可用
这是配置前必须亲手敲一遍的步骤，跳过等于白配。
- 打开终端（macOS/Linux）或 CMD/PowerShell（Windows），依次运行：
latexmk -v —— 必须输出类似 Latexmk, John Collins, 29 May 2023. Version 4.79xelatex --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、abstract.tex 等所有子文件顶部，**第一行且仅一行**写：
%!TEX root = main.tex
- 注意：
- 等号两边不能有空格（%!TEX root=main.tex ❌）
- 不能写两行（比如和 % 注释块混在一起 ❌）
- 不能放在第二行（哪怕前面只有一行空行 ❌）
PDF 查看器必须支持 SyncTeX 且正确绑定
Skim（macOS）、SumatraPDF（Windows）、zathura（Linux）是唯三被 LaTeXTools 原生支持的查看器。系统自带预览器（如 macOS 的 Preview.app）不支持反向搜索。
- macOS：装 Skim 后，进 Preferences → Sync，勾选「Enable SyncTeX」，并把「PDF viewer」设为 Sublime Text
- Windows：用 SumatraPDF，无需额外设置，但确保安装路径不含中文或空格
- Linux：用 zathura，需启用 D-Bus：zathura --synctex 启动，且 Sublime 配置中设 "view_pdf_viewer": "zathura"
- 关键细节：PDF 文件和 .synctex.gz 必须在**同一目录**、**同名**；若用了 includeonly{} 或输出到 output/ 子目录，SyncTeX 就会失效
最常被忽略的其实是 Sublime Text 启动方式——从 Dock 或 Launchpad 启动的 macOS 版本，往往读不到 shell 配置里的 PATH，导致控制台里 import os; print(os.environ.get('PATH')) 输出为空或不全。这时候得用终端启动：open -a "Sublime Text" --args，否则再准的配置也调不动命令。
