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 -synctex1 -interactionnonstopmode -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 -synctex1 -interactionnonstopmode -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 -interactionnonstopmode -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 让日志更“话多”的两个开关默认配置下有些错误会被-interactionnonstopmode吞掉一部分细节。我建议在排查阶段临时加上两个参数-file-line-error让错误带上文件名和行号-halt-on-error让编译在第一个错误处就停下而不是继续跑出一堆连锁错误。这样日志会短很多第一个错误就是根因。在配方配置里这两个参数通常长这样{ name: xelatex, tools: [xelatex], args: [-synctex1, -interactionnonstopmode, -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\windowsMiKTeX 通常在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: [-synctex1, -interactionnonstopmode, -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: [-synctex1, -interactionnonstopmode, %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和.bcfbiber读取.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说明用的是 pdflatexThis 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.texWindows 上能过Linux 上就报找不到文件进而配方失败。跨平台项目要特别注意统一大小写。7. 权限、杀毒与路径中文那些让人抓狂的外部因素7.1 文件被占用或只读编辑器在编译时需要写入.aux、.pdf等文件。如果这些文件被其他程序占用比如 PDF 阅读器正开着生成的 PDF或者项目目录是只读的写入就会失败配方随之终止。日志里通常写I cant 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或者干脆没有明确错误。把项目移到浅层目录就好了。这个坑很隐蔽因为报错信息完全不提路径长度。这些经验都不是看文档能学到的都是实际编译失败几十次之后总结出来的。希望你看完能少走点弯路。遇到这个报错别慌按流程一步步来绝大多数情况都能自己解决。 
长河君 · 2026/10/21 17:23:42 · 阅读 1.2k LaTeX编译报错Recipe terminated with error？从日志到修复的完整排查指南
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 -synctex1 -interactionnonstopmode -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 -synctex1 -interactionnonstopmode -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 -interactionnonstopmode -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 让日志更“话多”的两个开关默认配置下有些错误会被-interactionnonstopmode吞掉一部分细节。我建议在排查阶段临时加上两个参数-file-line-error让错误带上文件名和行号-halt-on-error让编译在第一个错误处就停下而不是继续跑出一堆连锁错误。这样日志会短很多第一个错误就是根因。在配方配置里这两个参数通常长这样{ name: xelatex, tools: [xelatex], args: [-synctex1, -interactionnonstopmode, -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\windowsMiKTeX 通常在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: [-synctex1, -interactionnonstopmode, -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: [-synctex1, -interactionnonstopmode, %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和.bcfbiber读取.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说明用的是 pdflatexThis 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.texWindows 上能过Linux 上就报找不到文件进而配方失败。跨平台项目要特别注意统一大小写。7. 权限、杀毒与路径中文那些让人抓狂的外部因素7.1 文件被占用或只读编辑器在编译时需要写入.aux、.pdf等文件。如果这些文件被其他程序占用比如 PDF 阅读器正开着生成的 PDF或者项目目录是只读的写入就会失败配方随之终止。日志里通常写I cant 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或者干脆没有明确错误。把项目移到浅层目录就好了。这个坑很隐蔽因为报错信息完全不提路径长度。这些经验都不是看文档能学到的都是实际编译失败几十次之后总结出来的。希望你看完能少走点弯路。遇到这个报错别慌按流程一步步来绝大多数情况都能自己解决。