sublime text 安装 latextools 失败主因是 package control 未安装或未更新,需先通过控制台安装 package control 并重启;编译失败多因 latexmk 路径、构建系统及主文件注释(% !tex root)未正确配置;pdf 预览问题源于查看器不支持 synctex 或未启用;中文编译应优先选用 xelatex + ctex 文档类,并确保文件编码为 utf-8。

Sublime Text 装不了 LaTeXTools?先确认 Python 环境和包管理器
Sublime Text 本身不带包管理器,LaTeXTools 必须通过 Package Control 安装——但很多人卡在这一步,不是插件问题,是 Package Control 没装好或没更新。
- 按
Ctrl+Shift+P(Win/Linux)或Cmd+Shift+P(macOS),输入Install Package Control,如果没这个选项,说明还没装;去官网复制安装脚本,粘贴进 Sublime 的 Python 控制台(Ctrl+`)运行 - 装完重启 Sublime,再按
Ctrl+Shift+P,搜Package Control: Install Package,等几秒加载完源列表,再搜LaTeXTools - 如果搜不到,可能是源没同步成功:菜单栏
Preferences → Package Settings → Package Control → Settings,检查channels是否包含https://packagecontrol.io/channel_v3.json
LaTeXTools 编译失败:路径、引擎、主文件三者必须对齐
装完插件不代表能编译。常见报错如 latexmk not found 或 File not found: main.pdf,本质是 Sublime 不知道用哪个命令、在哪找引擎、从哪开始编译。
-
latexmk是推荐的编译工具,Windows 推荐装Strawberry Perl+latexmk(MiKTeX 自带的latexmk常权限不足);macOS 用brew install latexmk;Linux 确保latexmk在$PATH里 - 在 Sublime 中右键 →
Set Build System → LaTeX,确保当前 build system 是LaTeX(不是LaTeX (Legacy)或空的) - 主文件必须含
% !TEX root = xxx.tex注释,否则插件找不到根文档;多文件项目中,子文件不能直接编译
PDF 预览打不开、跳转错乱?查 viewer 配置和反向搜索开关
预览失败不是插件坏了,而是 PDF 查看器没配对,或者反向搜索(Ctrl+Click 跳回源码)依赖的 synctex 文件没生成。
- 默认配置走系统默认 PDF 查看器,但 macOS 上 Preview 不支持反向搜索;建议改用
Skim(需在Preferences → Package Settings → LaTeXTools → Settings里设"viewer": "skim") - 确保编译命令启用了
-synctex=1(LaTeXTools默认已加,但如果自定义了builder_path或tex_path,可能被覆盖) - Windows 用户用 SumatraPDF,必须勾选设置里的
Enable SyncTeX,且 Sublime 设置中"forward_sync_command"要匹配其路径
中文编译报 Font T1/cmr/m/n/10=ecrm1000 at 10.0pt not loadable?别硬切引擎,先换文档类和编码
这个错误表面是字体缺失,实则是传统 latex 引擎对 UTF-8 和 CJK 支持差。强行装 ctex 包或改 fontenc 容易连锁出错。
- 直接用
xeCJK或ctex文档类,例如开头写\documentclass[UTF8]{ctexrep},并确保编译器设为xelatex(在LaTeXTools设置里改"builder": "traditional"→"program": "xelatex") - 不要用
inputenc+fontenc组合,XeLaTeX 下它们无效甚至冲突 - 如果仍报错,检查文件保存编码是否为 UTF-8(Sublime 右下角显示,
File → Save with Encoding → UTF-8)
最常被忽略的是:Sublime 的构建系统缓存不会自动清,改了设置后必须重启 Sublime 才生效;还有 Windows 用户把项目放在 OneDrive 或中文路径下,latexmk 会因路径空格或 Unicode 报错——这些细节比插件本身更影响体验。











