Sublime Text 需通过 LaTeXTools 插件与外部 TeX 发行版（如 TeX Live）协同工作，核心是确保 latexmk 可用、手动配置 texpath 路径、在子文件首行添加 %!TEX root 注释，并通过控制台查看真实编译错误。
Sublime Text 本身不内置 LaTeX 编译能力，必须通过插件（主要是 LaTeXTools）+ 外部 TeX 发行版（如 TeX Live 或 MiKTeX）协同工作。配置失败的绝大多数情况，不是 Sublime 设置错了，而是底层编译链没通——比如 latexmk 找不到、.tex 文件路径含中文、或默认构建系统没匹配到正确的引擎。
确认本地已安装可用的 TeX 发行版和 latexmk
这是最常被跳过的一步。没有 latexmk，LaTeXTools 几乎无法可靠编译多文件或带参考文献的论文。
- 在终端/命令行运行
latexmk -v，必须返回版本号（如Latexmk, John Collins, 29 May 2023. Version 4.79） - 若提示 command not found：Windows 用户装 MiKTeX 后需勾选「添加到系统 PATH」；macOS 用户用
brew install latexmk（前提是已装 MacTeX 或 BasicTeX）；Linux 用户通常随 TeX Live 一起安装，但可能需手动软链：sudo ln -s /usr/bin/latexmk /usr/local/bin/latexmk - 避免使用仅含
pdflatex的极简发行版（如某些 Docker 镜像），LaTeXTools默认依赖latexmk调度整个编译流程
安装 LaTeXTools 并禁用自动检测路径
LaTeXTools 的自动路径探测在多 TeX 环境或非标准安装路径下极易出错，建议手动指定关键路径。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 用 Package Control 安装
LaTeXTools后，打开Preferences → Package Settings → LaTeXTools → Settings – User - 粘贴以下最小必要配置（注意替换
texpath为你本地实际路径）：
{
"texpath": "/usr/texbin:/usr/local/texlive/2023/bin/x86_64-darwin",
"linux_texpath": "/usr/bin:/usr/local/texlive/2023/bin/x86_64-linux",
"osx_texpath": "/usr/texbin:/usr/local/texlive/2023/bin/x86_64-darwin",
"windows_texpath": "C:\texlive3\bin\win32",
"builder": "latexmk",
"command": ["latexmk"],
"output_directory": "",
"view_pdf_viewer": "auto"
}
-
texpath是核心：它必须包含latexmk、pdflatex、bibtex等可执行文件所在目录，多个路径用冒号（macOS/Linux）或分号（Windows）分隔 - 删掉
"use_simple_detection": true这类干扰项——它会让插件反复扫描 PATH，反而覆盖你手动设的路径
确保 .tex 文件顶部有正确的 %!TEX root 注释
论文通常由主文件（main.tex）和多个子文件（ch1.tex, refs.bib）组成。LaTeXTools 默认只编译当前打开的文件，除非你显式声明主文件。
- 在每个子
.tex文件第一行添加注释（必须是第一行，且无空格）：
%!TEX root = ../main.tex
- 路径支持相对路径，但不能跨盘符（Windows）或出现
~符号；推荐用../而非绝对路径，便于项目迁移 - 如果主文件含中文路径（如
/Users/张三/论文/main.tex），latexmk会静默失败——重命名为纯英文路径是最稳妥解法 - 保存后按
Ctrl+B（Windows/Linux）或Cmd+B（macOS），插件会自动切换到main.tex并调用latexmk编译整套文档
调试编译失败：看控制台输出，别只盯 PDF 是否生成
PDF 没更新？先别急着改 Sublime 设置。打开 Sublime 底部的 Ctrl+` 控制台，观察真实报错。
- 常见线索：
-
Can't locate LatexMk.pm→latexmk安装不完整，重装 TeX 发行版 -
Undefined control sequence DeclareUnicodeCharacter→ 主文件用了utf8x，换成utf8（现代 TeX Live 已弃用utf8x） -
Rule 'bibtex' failed→.bib文件路径错误，或ibliography{refs}中的refs不匹配实际文件名（不含.bib后缀） - 控制台无任何输出？检查
Settings – User中是否误加了逗号导致 JSON 解析失败，或texpath路径末尾多了斜杠（如/bin/→ 应为/bin）
真正卡住的地方，永远在 TeX 引擎那一层。Sublime 只是个触发器，它的配置越简单直接，越容易定位问题。
