sublime text latex 编译问题90%源于 latexmk/xelatex 未被系统识别，须终端验证命令可用性、手动配置 tex_path、强制使用 xelatex+ctex 编译、选用支持 synctex 的 pdf 阅读器并配对 subl 命令。
Sublime Text 本身不编译 LaTeX，所有“点不动 Ctrl+B”“PDF 空白”“中文变方块”“PDF 点击不跳回源码”的问题，90% 都是因为 latexmk 或 xelatex 根本没被系统识别——插件再配得细，也调不动不存在的命令。
确认 latexmk 和 xelatex 真的可用
别信安装界面勾了“加到 PATH”就完事。Sublime 启动时读不到 shell 的环境变量，但终端能反映真实状态。必须手动验证：
- 在终端（macOS/Linux）或 CMD/PowerShell（Windows）中运行
which latexmk（macOS/Linux）或where latexmk（Windows），必须返回一个具体路径，比如/usr/texbin/latexmk或C: exlive3inwin32latexmk.exe - 运行
xelatex --version，必须输出版本号；若报command not found，说明引擎没装或路径没通 - 运行
echo $PATH（macOS/Linux）或echo %PATH%（Windows），确认上一步返回的路径确实在其中 - 任一失败：macOS 重装
brew install --cask mactex；Windows 重装 MiKTeX 并**务必勾选「Add MiKTeX to the system PATH」**；Linux 补装sudo apt install latexmk。装完必须重启 Sublime
LaTeXTools 用户配置必须手动写死 tex_path，禁用自动探测
use_simple_detection 是个陷阱。它扫描 PATH 却忽略你实际 bin 目录的位置，尤其在 MacTeX 路径含空格、或 TeX Live 多版本共存时，100% 失效。进 Preferences → Package Settings → LaTeXTools → Settings – User，粘贴最小必要配置（删掉所有注释和空行）：
- macOS（MacTeX 默认）：
"tex_path": "/Library/TeX/texbin" - Windows（MiKTeX 或 TeX Live）：
"tex_path": "C:\texlive\2023\bin\win32"（注意双反斜杠） - Linux（TeX Live）：
"tex_path": "/usr/local/texlive/2023/bin/x86_64-linux" - 必须加
"builder": "latexmk"，否则默认可能 fallback 到不可靠的traditional构建器 - 删掉配置里任何
"use_simple_detection": true字段——它会覆盖你手动设的路径
中文编译必须靠 %!TEX program = xelatex + ctex，顺序不能错
用默认 pdflatex 编译中文，轻则方块字，重则直接报 Package ctex Error: No available font found。这不是缺宏包，是引擎与字体机制不匹配。
- 每个
.tex文件（包括子文件）**第一行且仅一行**写：%!TEX program = xelatex（注意空格、大小写、无多余字符） - 导言区第一行必须是
documentclass[UTF8]{ctexrep}或类似（ctexbook/ctexarticle），ctex宏包要放在最前，否则字体初始化失败 - 构建命令里强制走 XeLaTeX：
"cmd": ["latexmk", "-pdfxe", "-synctex=1", "-interaction=nonstopmode", "$file"]，-pdfxe比-xelatex更可靠 - 别混用
ctex和fontspec显式指定字体——ctex自动探测系统字体更省心；Linux 下若缺中文字体，先装fonts-wqy-zenhei等包
PDF 预览器必须支持 SyncTeX，且反向搜索要手动配对
Preview.app（macOS）、Adobe Acrobat、Edge 浏览器等都不支持反向搜索。Sublime 无法监听点击，必须靠 PDF 阅读器主动唤起编辑器并传参。
- macOS 必须用 Skim：官网下载安装 → Skim → Preferences → Sync → 勾选 “Check for file changes” → Presets → LaTeX → Set to “subl”，Arguments 填
--wait --line {line} "{file}" - Windows 必须用 SumatraPDF：安装后，在 LaTeXTools 设置里加
"viewer": "sumatrapdf"，并确保"sumatra_pdf_path"指向真实路径（如"C:\Program Files\SumatraPDF\SumatraPDF.exe"） - Linux 推荐 zathura + zathura-synctex 插件，设置
"viewer": "zathura"；用 evince 或 okular 只能手动刷新，不支持跳转 - 反向搜索失效的常见原因：
.fls文件没生成（说明编译根本没跑通）、subl命令不可用（需手动安装并加进 PATH）、PDF 查看器未启用 SyncTeX 支持
最容易被忽略的是 subl 命令——LaTeXTools 的正向/反向跳转、甚至部分构建流程都依赖它。没装 subl，Skim 就唤不起 Sublime，SumatraPDF 的 -inverse-search 参数也白设。装法见官方文档，装完必须重启终端和 Sublime 才生效。
