1. 从一次深夜编译失败说起：这个报错到底卡在哪
如果你在编辑器里写 LaTeX，十有八九见过这行红字：Recipe terminated with error. Retry building the project.。它不像语法错误那样告诉你第几行少了个括号，也不像缺包那样明确说File xxx.sty not found，它就是一个笼统的“配方执行失败”。很多人第一次遇到会反复点那个 Retry 按钮，点十次还是同样的结果，然后开始怀疑是不是编辑器坏了、是不是要重装。
我先把这个报错的性质说清楚：它不是编译错误本身，而是编译工具链调用失败的“外壳提示”。编辑器里负责构建的那套机制（通常叫 LaTeX Workshop 之类的扩展）会按照你配置的“recipe（配方）”去依次调用底层命令，比如latexmk、pdflatex、xelatex、biber等。只要这条调用链里任何一步返回了非零退出码，或者根本没找到可执行文件，扩展就会抛出这句通用提示。换句话说，真正的原因藏在更底层的日志里，这句红字只是“最后一公里”的报信人。
所以排查思路的核心只有一句话：不要盯着这句提示看，要去看它上面那几行真正的错误输出。编辑器一般会在“输出/Output”面板或者问题面板里打印完整的命令和 stderr。很多人忽略这一点，直接去搜这句提示，结果搜到的全是“重装扩展”“清缓存”这类治标不治本的建议。
这篇文章适合三类人：刚配好 LaTeX 环境、第一次撞上这个报错的新手；用了一段时间突然某天编译不过、找不到原因的老用户；以及想彻底搞懂编辑器构建机制、以后能自己看日志定位问题的进阶用户。我会按“先定位、再分类、后修复”的顺序，把最常见的几类根因一个个拆开讲，每一类都给出可复现的排查动作和修复方案。文中涉及的工具名、路径都是通用写法，你按自己机器上的实际情况替换即可。
提示：遇到这个报错，第一反应应该是打开输出面板，而不是点 Retry。Retry 只会用同样的配置再跑一遍，配置没变，结果必然一样。
2. 先学会读日志：把“配方失败”翻译成具体错误
2.1 输出面板里到底该看哪几行
编辑器的构建输出通常长这样：先打印一行它实际执行的命令，比如latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdf ...，然后是这条命令产生的所有标准输出和标准错误，最后才是那句Recipe terminated with error。你要找的是命令执行之后、报错提示之前的那段内容。
重点看三类信息：第一，命令本身有没有拼错，比如路径里带了空格却没加引号；第二，有没有command not found、is not recognized这类字样，说明可执行文件没进 PATH；第三，有没有 LaTeX 自己的错误，比如! LaTeX Error:、! Undefined control sequence、! Package xxx Error。这三类分别对应“配置问题”“环境问题”“文档问题”，处理方式完全不同。
我习惯的做法是先把输出面板的内容全选复制到一个临时文本里，然后从下往上找第一个以!开头的行，或者第一个包含Error、Fatal的行。那个位置往往就是真正的起点，它下面的内容才是连锁反应。
2.2 一个真实的日志片段拆解
假设你看到的是这样一段（我做了脱敏和简化）：
latexmk -cd -e -f -synctex=1 -interaction=nonstopmode -file-line-error -xelatex main.tex Latexmk: This is Latexmk, version 4.79 Latexmk: applying rule 'xelatex'... Rc files read: NONE Latexmk: Run number 1 of rule 'xelatex' xelatex -no-pdf -interaction=nonstopmode -file-line-error main.tex 'xelatex' is not recognized as an internal or external command Latexmk: Summary of warnings: ... Collected error summary (may duplicate other messages): xelatex: Command for 'xelatex' gave return code 1 Recipe terminated with error.这段日志的信息量很大。它告诉你：配方用的是latexmk驱动xelatex，但系统在调用xelatex时提示“不是内部或外部命令”，也就是根本没找到 xelatex 这个可执行文件。那问题就不在文档，而在环境变量或 TeX 发行版的安装上。修复方向立刻明确了：要么把 TeX 的 bin 目录加进 PATH，要么在编辑器配置里写死可执行文件的绝对路径。
反过来，如果日志里出现的是! LaTeX Error: File 'ctex.sty' not found，那就是缺宏包，跟 PATH 无关，需要装包或换编译器。你看，同样是“配方失败”，根因天差地别，所以读日志这一步绝对不能跳过。
2.3 让日志更“话多”的两个开关
默认配置下，有些错误会被-interaction=nonstopmode吞掉一部分细节。我建议在排查阶段临时加上两个参数：-file-line-error让错误带上文件名和行号，-halt-on-error让编译在第一个错误处就停下，而不是继续跑出一堆连锁错误。这样日志会短很多，第一个错误就是根因。
在配方配置里，这两个参数通常长这样：
{ "name": "xelatex", "tools": ["xelatex"], "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-halt-on-error"] }等环境稳定了，你可以把-halt-on-error去掉，因为它会让编译在遇到小警告时也停下，影响正常写作。但排查阶段它是神器。
3. 环境变量与可执行文件：最常见的“找不到命令”根因
3.1 为什么装了 TeX 还是提示找不到命令
这是新手遇到这个报错的第一大原因。TeX 发行版（无论是 TeX Live 还是 MiKTeX）安装完之后，它的可执行文件目录必须被加入系统的 PATH 环境变量，编辑器才能在任何位置调用到pdflatex、xelatex、latexmk这些命令。很多人安装时没勾选“添加到 PATH”，或者装完没重启编辑器，导致编辑器继承的还是旧的 PATH。
判断方法很简单：打开系统自带的终端（不是编辑器内置终端），直接敲xelatex --version。如果终端里能正常输出版本号，而编辑器里报找不到命令，那就是编辑器没继承到新 PATH，重启编辑器甚至重启系统即可。如果终端里也提示找不到，那就是 PATH 本身没配好。
Windows 上 TeX Live 的 bin 目录通常形如C:\texlive\2024\bin\windows，MiKTeX 通常在C:\Program Files\MiKTeX\miktex\bin\x64。macOS 上 TeX Live 的路径一般是/usr/local/texlive/2024/bin/universal-darwin或者通过/Library/TeX/texbin这个软链接访问。Linux 上常见的是/usr/local/texlive/2024/bin/x86_64-linux或发行版包管理器安装的/usr/bin。
3.2 在编辑器配置里写死绝对路径
如果你不想动系统 PATH（比如公司电脑没权限），最稳的办法是在编辑器配置里直接指定可执行文件的绝对路径。以 LaTeX Workshop 为例，可以这样写：
{ "latex-workshop.latex.tools": [ { "name": "xelatex", "command": "/usr/local/texlive/2024/bin/universal-darwin/xelatex", "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"] } ] }Windows 上路径要写成C:\\texlive\\2024\\bin\\windows\\xelatex.exe，注意 JSON 里反斜杠要转义。这样即使 PATH 有问题，编辑器也能找到命令。代价是以后升级 TeX 版本要记得改路径，所以我一般建议优先修 PATH，绝对路径作为兜底。
注意：路径里如果包含空格（比如
Program Files），在 JSON 字符串里没问题，但如果是在命令行里手动测试，一定要用引号包起来，否则会被拆成多个参数。
3.3 一个容易被忽略的坑：编辑器内置终端和系统终端不一致
有些编辑器有“内置终端”，它继承的环境变量可能和系统终端不同，尤其是在 Windows 上通过某些方式启动编辑器时。我遇到过这样的情况：系统终端里latexmk --version正常，编辑器内置终端里却找不到。原因是编辑器是从图形界面启动的，没有加载登录 shell 的配置文件。
解决办法有两个：一是从终端里用命令启动编辑器，让它继承当前 shell 的环境；二是在编辑器配置里显式设置环境变量。后者更可靠，比如：
{ "latex-workshop.latex.tools": [ { "name": "xelatex", "command": "xelatex", "args": ["-synctex=1", "-interaction=nonstopmode", "%DOC%"], "env": { "PATH": "/usr/local/texlive/2024/bin/universal-darwin:/usr/bin:/bin" } } ] }这样就把 PATH 固定下来了，不依赖外部环境。
4. 配方配置本身写错了：工具链顺序与参数陷阱
4.1 配方是什么，为什么它会“终止”
配方（recipe）就是一条流水线，规定了“先跑哪个工具、再跑哪个工具、每个工具带什么参数”。比如一篇用了中文和参考文献的文档，典型流水线是：xelatex编译一次生成辅助文件，biber处理参考文献，再xelatex跑两次让交叉引用和目录稳定。只要其中任何一步失败，整条流水线就终止，报出那句通用提示。
所以配方失败有两种可能：一是某个工具本身报错（文档问题），二是配方把工具的顺序或参数配错了（配置问题）。后者经常被忽略，因为用户会以为是文档写错了。
4.2 工具顺序配错的典型症状
最常见的顺序错误是：用了biber却把bibtex写进了配方，或者参考文献工具放在了最后一次编译之后。前者会报“找不到 .bbl 文件”或 biber 相关错误，后者会导致参考文献不显示但编译“成功”。还有一种是把latexmk和手动多步编译混用，导致重复编译或参数冲突。
一个稳妥的多步配方长这样：
{ "name": "xelatex -> biber -> xelatex*2", "tools": ["xelatex", "biber", "xelatex", "xelatex"] }注意xelatex出现三次：第一次生成.aux和.bcf，biber读取.bcf生成.bbl，后两次让引用和目录收敛。少跑一次都可能出现问号引用。
4.3 参数里的隐藏陷阱：%DOC%和文件路径
LaTeX Workshop 用%DOC%表示当前主文件名（不含扩展名），%DOCFILE%表示带扩展名的完整文件名。如果你在参数里写死了main.tex，那么换一个主文件就编译不了，报错也是这句通用提示。正确做法是用占位符。
另一个陷阱是-cd参数。它让 latexmk 切换到文档所在目录再编译，适合多文件项目。但如果你的配方里同时用了相对路径的图片或宏包，-cd可能让相对路径失效。我一般建议：单文件项目不加-cd，多文件项目加-cd并确保所有路径都是相对于主文件的。
还有一个经典问题：-output-directory把输出放到子目录，但某些工具（如 biber）默认在当前目录找辅助文件，导致找不到而失败。如果要用输出目录，记得给 biber 也加上对应的目录参数，或者干脆不用输出目录，让所有文件生成在一起。
5. 宏包缺失与编译器不匹配：文档层面的“配方失败”
5.1 缺包为什么也会报“配方终止”
前面说过，配方里任何一步返回非零退出码都会触发这句提示。当 LaTeX 找不到某个宏包时，它会报File 'xxx.sty' not found并返回非零码，于是配方终止。这类问题的特征是：日志里能明确看到缺哪个包，而且往往在你换了一台机器、或者用了别人模板之后突然出现。
修复方式取决于你的发行版。TeX Live 用tlmgr install 包名，MiKTeX 通常会自动弹窗提示安装，或者用mpm --install=包名。如果不知道包名对应哪个宏包，可以在 CTAN 上搜一下。注意有些包名和\usepackage{}里写的名字不完全一致，比如\usepackage{geometry}对应的包名就是geometry，但有些字体包名字会有前缀。
5.2 编译器选错：xelatex 和 pdflatex 的恩怨
中文文档是重灾区。pdflatex对中文支持很差，直接编译带中文的文档会报一堆Missing character或者直接失败。正确做法是用xelatex或lualatex，它们原生支持 Unicode 和系统字体。如果你用ctex宏包，它其实会根据编译器自动适配，但前提是你真的用了 xelatex。
判断方法：看日志第一行，This is pdfTeX说明用的是 pdflatex，This is XeTeX说明是 xelatex。如果文档里有中文却跑的是 pdflatex，那基本就是编译器选错了。改配方里的工具名即可。
还有一种情况是文档用了fontspec宏包指定系统字体，这个宏包只能在 xelatex/lualatex 下工作，pdflatex 下直接报错。这类错误日志里会写Package fontspec Error: The fontspec package requires either XeTeX or LuaTeX，看到这句就换编译器，不用犹豫。
5.3 字体缺失：日志里最不显眼但最致命的一类
用 xelatex 指定了某个系统字体，但这台机器上没装，编译会失败。日志里通常写The font "XXX" cannot be found。这类问题在跨平台协作时特别常见：别人在 macOS 上用苹方字体，你在 Windows 上没这个字体，编译就挂。
解决办法有两个：一是换成通用字体（如Noto Serif CJK），二是把字体文件放进项目目录用路径引用。后者更可控，适合需要精确排版的场景。我一般建议团队协作时统一用开源字体，避免依赖系统预装。
6. 缓存与辅助文件作祟：清一次就好使的玄学问题
6.1 什么时候该怀疑缓存
如果你昨天还能编译，今天改了几行就报配方失败，而且日志里的错误看起来莫名其妙（比如引用了不存在的标签、目录错乱），那很可能是辅助文件（.aux、.bbl、.toc、.out）处于不一致状态。LaTeX 的交叉引用机制依赖这些中间文件，一旦它们和当前源码不同步，就会出现各种诡异错误。
最典型的场景是：你删了一个\label，但.aux里还留着旧引用，编译时就会报Reference undefined或者直接失败。另一个场景是参考文献：你改了.bib文件但没重新跑 biber，.bbl还是旧的，引用就对不上。
6.2 清理的正确姿势
不要手动一个个删，容易漏。LaTeX Workshop 自带“Clean up auxiliary files”命令，在命令面板里搜latex-workshop clean就能找到。它会按配置的扩展名列表清理。你也可以在配置里自定义要清理的文件类型：
{ "latex-workshop.latex.clean.fileTypes": [ "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.fls", "*.log", "*.fdb_latexmk", "*.snm", "*.nav" ] }清理完再编译一次，很多“玄学”问题就消失了。我的习惯是：每次大改结构（增删章节、改参考文献）之后，先清理再编译，能省掉大量排查时间。
6.3 输出目录残留导致的“幽灵错误”
如果你配置了输出目录，旧版本编译产生的文件可能残留在那里，新编译读取到旧文件就会出错。尤其是.aux文件，它记录了上一次的页码和引用，和新源码不匹配时就会报错。解决办法是清理时把输出目录也纳入范围，或者干脆不用输出目录。
还有一种情况是文件名大小写问题。Windows 和 macOS 默认文件系统不区分大小写，Linux 区分。如果你在 Windows 上写\input{Chapter1}而实际文件是chapter1.tex，Windows 上能过，Linux 上就报找不到文件，进而配方失败。跨平台项目要特别注意统一大小写。
7. 权限、杀毒与路径中文：那些让人抓狂的外部因素
7.1 文件被占用或只读
编辑器在编译时需要写入.aux、.pdf等文件。如果这些文件被其他程序占用（比如 PDF 阅读器正开着生成的 PDF），或者项目目录是只读的，写入就会失败，配方随之终止。日志里通常写I can't write on file 'xxx.aux'或Permission denied。
解决办法很直接：关掉占用文件的程序，检查目录权限。Windows 上还要注意“只读”属性，有时候从压缩包解压出来的文件会带上只读标记，导致编译失败。右键属性去掉只读即可。
7.2 杀毒软件拦截
这个坑比较隐蔽。某些杀毒软件会把 LaTeX 编译过程中频繁读写大量小文件的行为判定为可疑，临时锁定文件或直接拦截进程，导致编译随机失败。特征是：同样的文档，有时候能编译，有时候报错，没有规律。
排查方法是临时关闭实时防护再编译一次。如果问题消失，就把 TeX 的 bin 目录和项目目录加入白名单。这个操作因软件而异，但思路是一样的：让杀毒软件信任编译工具链。
7.3 路径里的中文和空格
LaTeX 工具链对非 ASCII 路径的支持一直不太好，尤其是老版本的latexmk和某些宏包。如果你的项目放在D:\我的文档\论文\这样的路径下，很可能编译失败，日志里会出现乱码或者File not found。
最省事的办法是把项目移到纯英文、无空格的路径下，比如D:\projects\paper\。如果必须用中文路径，确保所有工具都是较新版本，并且在配方里给路径加引号。但说实话，与其和路径较劲，不如换个目录，省下的时间够写好几页了。
8. 一套可复用的排查流程：从报错到修复的完整链路
8.1 五步定位法
我把上面所有内容浓缩成一套流程，遇到这个报错按顺序走：
第一步，打开输出面板，从下往上找第一个真正的错误行，忽略那句通用提示。第二步，看错误类型：是“找不到命令”还是“LaTeX 错误”还是“权限/写入错误”。第三步，如果是找不到命令，去系统终端验证命令是否存在，检查 PATH 或改用绝对路径。第四步，如果是 LaTeX 错误，看是缺包、编译器不匹配还是字体问题，对应处理。第五步，如果以上都不是，清理辅助文件后重试，再不行就检查路径、权限和杀毒软件。
这套流程覆盖了我遇到过的九成以上情况。剩下的那一成，通常是多个问题叠加，比如既缺包又路径有中文，那就一个个解决，每解决一个编译一次，看错误有没有变化。
8.2 一个最小可复现示例
为了让你能自己验证，我给一个最小文档：
\documentclass{article} \usepackage{ctex} \begin{document} 你好，世界。 \end{document}保存为test.tex，用 xelatex 配方编译。如果这个能过，说明环境基本没问题，问题在你的主文档里。如果这个都过不了，那就是环境或配置问题，按前面的章节排查。这个方法能快速区分“环境问题”和“文档问题”，非常实用。
8.3 配置备份与版本管理
最后分享一个习惯：把编辑器的配置文件（settings.json）纳入版本管理，或者至少定期备份。LaTeX 环境配置一旦调好，能稳定用很久，但换机器或重装系统后重新配一遍很痛苦。我见过太多人因为换了电脑，之前调好的配方全丢了，又从头踩一遍坑。
配置文件不大，放到一个私有仓库里，换机器时拉下来改改路径就能用。同时记录一下自己用的 TeX 发行版版本和关键宏包版本，出问题时能快速对比。这个习惯看起来麻烦，但真出事的时候能救命。
提示：如果你用的是团队协作模板，建议把编译配方也写进项目文档，让每个人用同样的工具链，能避免大量“在我机器上能编译”的扯皮。
9. 我在实际配置中踩过的几个具体坑
第一个坑是latexmk的-cd参数和%DOC%的配合。有一次我把-cd加进配方，结果%DOC%展开成了相对路径，latexmk 切换目录后就找不到主文件了。后来改成%DOCFILE%并确保路径是相对于项目根目录的，才稳定下来。这个细节文档里写得不清不楚，只能自己试。
第二个坑是 biber 的版本和 biblatex 宏包版本不匹配。升级了 TeX 发行版之后，biber 也跟着升级，但文档里用的 biblatex 还是旧版，结果 biber 报了一堆看不懂的格式错误。解决办法是同时升级 biblatex 宏包，或者锁定版本。这类版本兼容问题在滚动更新的发行版上很常见。
第三个坑是 Windows 上的路径长度限制。项目嵌套太深，加上辅助文件的长文件名，总路径超过 260 字符，写入就失败。日志里报的是File name too long或者干脆没有明确错误。把项目移到浅层目录就好了。这个坑很隐蔽，因为报错信息完全不提路径长度。
这些经验都不是看文档能学到的，都是实际编译失败几十次之后总结出来的。希望你看完能少走点弯路。遇到这个报错别慌，按流程一步步来，绝大多数情况都能自己解决。
