有人把一份 .tex 文件发过来说双击打开是一堆反斜杠和花括号问怎么才能变成一份能打印的 PDF。这种场景我遇到过太多次了。问题往往不在文档本身而在于他那台机器上根本没装 LaTeX 环境或者装了但命令行找不到再或者装了却因为中文字体没配好一编译就抛出一屏看不懂的报错。LaTeX 这个东西的门槛从来不在语法而在于从零到第一次成功出 PDF 之间那段没人给你讲清楚的路。TeX Live 是目前覆盖面最广的一套发行版跨平台、宏包齐全、维护也稳定但它动辄几个 G 的体积、安装器里一堆英文选项、装完之后还要配编辑器、配字体、配编译链任何一环掉链子都会让人卡在原地。这篇内容就是围绕 TeX Live 的安装与配置展开的从概念辨析讲到分平台安装从命令行验证讲到中文排版链路再到编辑器联动和长期维护。适合三类人完全没接触过、想一次性把环境搭对的新手装过但一直靠某个现成模板勉强能用、不清楚背后在发生什么的人以及想把这套工具真正用顺手、用来写论文写报告写简历的老用户。我不会只给一串命令让你复制粘贴每个选项为什么这么选、每个报错背后是什么机制都会讲清楚。毕竟环境这件事装对了能省下后面几个月的折腾。1. 动手之前先分清 TeX、LaTeX、发行版与编辑器1.1 一条编译链上的四个角色很多人第一次接触这套东西时脑子是乱的因为听到的名词太多TeX、LaTeX、XeLaTeX、TeX Live、CTeX、TeXstudio、VS Code。其实把它们摆到一条流水线上各自的位置非常清楚。TeX 是底层的排版引擎本质是一个把标记语言转成排版指令的程序它只认识非常原始的命令。LaTeX 是架在 TeX 之上的一套宏包集合把“我要一个章节标题”“我要一个居中的表格”这种常见需求封装成了\section{}、\begin{table}这样的写法。你写的是 LaTeX最终干活的是 TeX 引擎。而 XeLaTeX、LuaLaTeX、pdfLaTeX 是同一底层的不同引擎变体区别在于对字体、编码、Unicode 的支持程度这一点在中文场景里极其关键后面会专门讲。发行版是“引擎 成千上万个宏包 字体 配套工具”的打包产物TeX Live 就是其中最主流的一个。编辑器则是你敲字的地方它本身不参与排版只是调用发行版里的命令再把生成的 PDF 显示给你看。搞清这四层关系之后你就能明白一个很常见的困惑为什么在编辑器里点了个绿色的运行按钮报错却说xelatex: command not found——因为编辑器只是个壳它去调用系统里的 xelatex而系统里没有。1.2 发行版怎么选三家的实际差异主流的发行版就那么几个选错了后面会反复难受所以值得花两分钟对比。发行版覆盖平台体积完整安装装包方式适合的场景TeX LiveWindows / Linux / macOS 通用约 7–8 GB自带 tlmgr 统一管理长期使用、跨平台、想一次装全MiKTeX主要是 Windows初始约 300 MB按需下载编译时缺什么自动弹窗下载磁盘紧张、只在 Windows 上用MacTeX仅 macOS约 5 GB底层就是 TeX Live加了些 Mac 工具macOS 用户图省事MiKTeX 的“按需下载”听起来很美实际用起来的体验是你正忙着改论文编译突然弹出一个对话框问你要不要装某个宏包网络一慢就卡在那里而且不同机器上装出来的宏包版本可能不一致别人能编译你不一定能。TeX Live 的思路相反一次装全之后所有宏包都在本地哪怕断网也能编译版本也可控。做长期项目、需要跟别人交换源码的时候这个一致性比省那几 G 空间重要得多。macOS 用户可以直接装 MacTeX它就是把 TeX Live 做了 Mac 化封装装完还顺带给你一些图形化小工具。Linux 用户有两个选择用发行版仓库里的texlive-full或者用官方的install-tl脚本。前者省事但版本往往落后一两年某些新宏包用不了后者版本新、可控代价是要多敲几条命令。我个人偏向官方脚本因为 LaTeX 生态里宏包版本不匹配引发的报错非常隐蔽用新版本能少踩很多莫名其妙的坑。1.3 年份版本与磁盘布局决定了后面所有配置TeX Live 是每年发布一个版本的目录名带年份比如texlive/2024、texlive/2025。这个设计不是随便定的它意味着你可以在同一台机器上并存两个年份的版本用 PATH 切换。这个能力在关键时刻能救命某次更新之后你的论文突然编不过了把 PATH 指回旧年份立刻恢复不用连夜排查。典型的安装后目录结构长这样以 Windows 装到C:\texlive\2025为例bin\windows\所有可执行文件xelatex.exe、latexmk.exe、tlmgr.bat都在这里texmf-dist\发行版自带的宏包、字体、文档体量最大的一部分texmf-local\留给你自己放私有宏包和字体的地方升级时不会被覆盖texmf-var\字体缓存、格式文件等运行时生成的东西tlpkg\tlmgr 自己的数据库和配置这里有个经验自己写的宏包、下载的模板类文件一律放到texmf-local下对应的目录里不要往texmf-dist里塞。后者是发行版管理的区域一次更新就可能被覆盖或产生冲突。放进texmf-local之后跑一次texhash刷新数据库系统就能找到而且升级年份版本时可以整个目录拷过去非常省事。2. 安装包获取与分平台安装的实操细节2.1 先校验再运行这一步别省安装包体积不小下载过程中出点差错是常有的事校验一下能避免后面出现“装到一半报错、报错信息还看不懂”的尴尬。官方在发布目录里会同时提供.sha512校验文件。Linux 或 macOS 上把安装包和校验文件放在同一个目录执行sha512sum -c install-tl-unx.tar.gz.sha512看到OK就说明文件完整。Windows 上用自带工具算一遍再和校验文件里的字符串比对certutil -hashfile install-tl-windows.exe SHA512输出是一长串十六进制去掉空格后和官网给出的值逐位对比。这一步花不了一分钟但能挡掉一类最难查的问题——文件损坏导致的安装器崩溃报错信息通常指向某个莫名其妙的位置你会以为是系统环境问题查半天。提示下载源尽量选一个网络可达、速度稳定的镜像站。安装器在安装过程中还会继续从源站拉取文件所以源站选择不只影响下载安装包那一下还影响整个安装过程的耗时。装完之后可以用 tlmgr 单独把源换掉这个后面讲。2.2 Windows安装器里那几个勾选项的含义Windows 上双击install-tl-windows.exe会先解压出一个带图形界面的安装器。界面上的选项不多但每一个都影响后面的使用体验值得逐个说。安装范围选“仅为当前用户安装”还是“为所有用户安装”。前者不需要管理员权限装到用户目录下后者需要 UAC 提权装到C:\texlive\年份。如果这台机器只有你一个人用选前者也没问题但要注意路径里可能带用户名某些老旧的构建脚本对长路径不太友好。我一般选“所有用户”加固定路径省心。安装目录默认是C:\texlive\2025。强烈建议保持这个默认值不要装到桌面、不要在路径里放空格和中文。这条不是洁癖是实打实踩过的坑某些底层工具在拼接路径时对空格处理不当C:\Users\张三\Desktop\我的论文\texlive这样的路径会在你完全意想不到的环节炸掉而且报错信息完全看不出跟路径有关。创建符号链接默认不勾。这个选项需要系统开启开发者模式或者管理员权限勾了容易在安装阶段报权限错误而它对普通用户几乎没有价值保持不勾。把 TeX Live 加入 PATH这个一定要勾。勾了之后你在任意目录打开命令行都能直接敲xelatex编译。不勾的话所有命令都得写全路径或者事后手动配环境变量多一道麻烦。万一当时漏勾了也不致命后面手动加一下就行。安装完成后不要急着点完成安装器在最后会做一些收尾工作比如生成格式文件、刷新文件名数据库ls-R这个过程要跑几分钟命令行窗口里会滚动大量输出。有人看到进度条走完就直接关掉了结果宏包找不到、命令报奇怪的错原因就是收尾没跑完。2.3 macOS 与 Linux.pkg 与 install-tl 的差别macOS 上最省事的做法是装 MacTeX 的.pkg双击一路下一步装完/usr/local/texlive/2025/bin/自动出现在 PATH 里命令行直接可用。它的完整版体积五六个 G如果磁盘紧张可以在安装时选择“ BasicTeX 按需装包”的路线但如前所述按需装包在项目协作场景下会带来版本不一致的问题。Linux 上我更推荐用官方脚本操作路径如下。先解压tar -xzf install-tl-unx.tar.gz cd install-tl-2025*然后用文本界面安装./install-tl进去之后是一屏纯文本菜单第一次看会有点懵记住几个关键按键就够了D改安装目录S选安装方案O改其他选项I开始安装Q退出。如果你想让安装过程完全无人值守可以先把配置写进一个 profile 文件再用-profile参数调用selected_scheme scheme-full TEXDIR /opt/texlive/2025 TEXMFLOCAL /opt/texlive/texmf-local./install-tl -profile texlive.profile --no-interaction这样写的好处是配置可复现下次换机器直接复用这个 profile不用再在菜单里点一遍。装完之后还有一步容易被忘TeX Live 不会自动把bin目录加到 PATH 里需要手动在~/.bashrc或~/.zshrc中追加export PATH/opt/texlive/2025/bin/x86_64-linux:$PATHLinux 上还有一个tlmgr path add命令可以自动建符号链接到/usr/local/bin效果类似。2.4 安装方案的选择full、medium 与按需装包安装器会让你选一个 scheme这一步直接决定了装多少东西。scheme-full全套7 GB 左右用了什么宏包都不用再下载scheme-medium中等约 1.5 GB覆盖常用宏包和中文支持scheme-basic最小几百 MB只有基础排版功能中文、绘图相关的宏包大多没有scheme-small比 basic 稍多一些但仍然很简陋磁盘允许的话直接上full。理由不是“反正空间大”而是 LaTeX 生态里最折磨人的就是“缺宏包”。你可能只是为了画一张流程图去用 TikZ结果它依赖一串你听都没听过的包或者导入别人的模板一编译报十几个File xxx.sty not found。full 方案把这些不确定性一次性消掉代价只是一块硬盘空间。早年我为了省空间装 basic结果光是装齐中文和绘图相关宏包就花了半小时还漏了两个。如果你确实选了精简方案后面的装包全靠 tlmgr这个工具用法在 3.4 节详细说。这里只强调一点装完之后先跑一次tlmgr update --self tlmgr update --all让本地宏包库和源站对齐减少版本错配。3. 装完之后的第一步命令行能不能跑起来3.1 PATH 与版本确认安装完成和“能用”之间还隔着一个 PATH。所谓 PATH就是系统的一份目录清单你在命令行敲xelatex时系统会按清单逐个目录去找这个名字的可执行文件找不到就报command not found或不是内部或外部命令。这不是软件装坏了是路径没配。验证方法很简单。Windows 的 PowerShell 里where.exe xelatex xelatex --versionLinux 或 macOS 上which xelatex xelatex --version第一条命令告诉你系统在哪找到了这个程序正常情况下应该指向texlive\2025\bin\...这个路径。第二条打印版本信息形如XeTeX 3.141592653-2.6-0.999996 (TeX Live 2025)。看到后者说明命令行层面彻底通了。如果where什么都没输出说明 PATH 没生效。Windows 上要检查系统环境变量里的Path项是否包含C:\texlive\2025\bin\windows加完之后必须关掉所有已打开的命令行窗口重新打开因为环境变量是在进程启动时读取的老窗口不会自动刷新。这一点坑过不少人改完变量在原窗口里验证半天没反应以为改错了。还有一个隐蔽情况机器上装过多个版本where xelatex输出好几行第一行是旧版本。系统按顺序取第一个所以你实际用的是旧版本。这时候要么调整 PATH 里条目的顺序要么干脆把旧版本的 bin 目录去掉。3.2 最小测试文档与首次编译环境通不通跑一个最小文档最直接。新建一个文件叫test.tex内容如下\documentclass{article} \begin{document} Hello, \LaTeX. \end{document}在该目录下执行pdflatex test.tex如果目录里出现了test.pdf恭喜基础链路是通的。注意这一步用pdflatex而不是xelatex因为纯英文文档用 pdflatex 更快也更能验证到底层引擎是否正常。这一过程会产生几个辅助文件.aux存交叉引用信息.log是完整日志.out是书签信息。.aux是多次编译之间传递数据的桥梁交叉引用要正确通常需要编译两到三遍第一遍收集后面几遍填值。这也是很多人第一次遇到“为什么我的目录页码是问号”的原因——只编译了一遍。3.3 首编失败的排查顺序与对照表第一次编译失败太正常了关键是有章法地查别抓瞎。日志文件很长新手最容易犯的错是从最后一行开始看而最后一行通常是被第一条错误引发的连锁反应。正确的做法是从日志开头往下找第一个以!开头的行那才是真正的病灶后面的都是次生灾害。把常见的首编报错整理成一张表对着查能省不少时间报错关键字真实原因处理办法command not found/不是内部或外部命令PATH 未生效检查环境变量重开终端File xxx.sty not found宏包缺失tlmgr install 包名不确定包名时用tlmgr search --global --file xxx.sty反查! Undefined control sequence命令拼错或用到的宏包没\usepackage检查是否漏引入宏包注意大小写! LaTeX Error: File xxx.cls not found文档类缺失模板文件没放对位置把 cls 文件放到源码同目录或放进 texmf-local! Package fontspec Error: The font xxx cannot be found字体没装或名字写错用fc-list :langzh查实际字体名! I cant find file xxx文件名拼错或路径含特殊字符核对文件名把路径改成纯英文无空格! Emergency stop.前面已有严重错误引擎放弃了往上找第一条报错卡在?提示符不动编译进入交互模式等你输入删掉进程加-interactionnonstopmode参数重跑最后一条值得多说一句。编译出错时引擎默认会停下来问你怎么处理等你输入指令。在命令行里手敲还好在编辑器里点按钮触发时就会表现为“一直卡着没反应”。养成加-interactionnonstopmode的习惯让它遇错就记录、继续往下走一次跑完拿到完整日志。3.4 tlmgr装包、更新与回滚tlmgr 是 TeX Live 的包管理器日常打交道的频率不低几个命令必须会。tlmgr update --self # 先更新 tlmgr 自己 tlmgr update --all # 更新所有已安装的包 tlmgr install ctex # 装一个包 tlmgr remove ctex # 卸一个包 tlmgr info ctex # 看包的信息和版本 tlmgr search --global --file ctex.sty # 已知文件名反查包名search --global --file这个用法值得记住。报错告诉你缺foo.sty但包名不叫 foo 的情况非常普遍硬猜会浪费很多时间。用文件名反查一步到位。换源是另一个高频操作。默认源在有些网络环境下速度很慢换成一个可达的镜像站能快一个数量级tlmgr option repository https://mirror.example.org/texlive/2025/tlpkg/换成你自己实测速度较好的镜像地址即可注意路径要精确到年份目录下的tlpkg。回滚功能是救命稻草。宏包更新之后某个老文档突然编不过了这时候不需要从头查直接把那个包退回旧版本tlmgr info 包名 # 输出里会列出可用的历史版本号 tlmgr restore 包名 版本号我遇到过几次 biblatex 和 biber 版本不同步的问题就是靠 restore 解决的。这两个包必须版本匹配更新其中一个却没更新另一个就会出现文献编译失败报错信息还非常晦涩。所以跑tlmgr update --all之前心里要有数更新的不只是你主动装的东西依赖链上的所有包都会动。4. 中文文档这条链路最容易断在哪里4.1 默认模板写中文为什么报错把 3.2 节那个测试文档里的英文改成中文再用 pdflatex 编译你会得到一堆关于字符的报错。原因在于 pdflatex 处理的是 8 位编码它不认识 UTF-8 里的三字节汉字序列遇到就当非法字符处理。这不是“LaTeX 不支持中文”而是引擎选错了。XeLaTeX 从设计上就按 Unicode 处理输入直接对接系统字体中文、日文、阿拉伯文都不在话下。所以中文文档的编译链是源码用 UTF-8 编码保存用 XeLaTeX 编译。这两条缺一不可。源码编码这一条还有个小坑Windows 记事本早年保存 UTF-8 时会加一个 BOM 头这个不可见字符跑到文档开头会让引擎报Unknown character位置在第 1 行第 1 列肉眼完全看不出来。用 VS Code 之类的编辑器保存时确认选择“UTF-8”而不是“UTF-8 with BOM”就行。4.2 ctex 文档类与宏包的取舍中文排版不只是“能显示汉字”标点间距、段落首行缩进、章节标题的字体、图表标题格式都跟英文默认规则不同。ctex 这套东西就是来干这个的它有两种用法。第一种是直接用 ctex 提供的文档类把article换成ctexart、report换成ctexrep、book换成ctexbook\documentclass[UTF8,12pt]{ctexart} \usepackage{geometry} \geometry{a4paper,margin2.5cm} \begin{document} 这是一个中文测试文档用来验证排版链路。 \section{第一节} 正文内容。 \end{document}这种写法最省事中文相关的配置它全包了首行缩进、标点挤压、章节标题格式都是对的。新手直接用这个别折腾。第二种是保留原有的英文文档类额外引入 ctex 宏包\documentclass{article} \usepackage[UTF8]{ctex}适合的场景是你拿到一个英文模板很多期刊模板、会议模板都是英文文档类但需要往里写中文。注意这种方式下模板本身对字体和版式做过定制和 ctex 的默认设置可能打架出现标题字体不对、间距怪异的概率不低需要手工调。4.3 字体集与 fontset 选项的实际情况ctex 会根据操作系统自动选一套中文字体这个选择由fontset选项控制。在 Windows 上默认是windows用系统自带的宋体、黑体、楷体、仿宋macOS 上默认macLinux 上默认fandol。fandol是一套开源中文字体随 TeX Live 一起装好处是不依赖系统装了什么字体坏处是字形覆盖不全、字重选择少某些生僻字会缺。如果你在 Linux 上想要更好的效果可以显式指定\documentclass[UTF8,fontsetfandol]{ctexart}或者在系统里装了思源系列字体的情况下直接绕过 fontset 手动指定\usepackage[UTF8]{ctex} \setCJKmainfont{Noto Serif CJK SC} \setCJKsansfont{Noto Sans CJK SC} \setCJKmonofont{Noto Sans Mono CJK SC}判断系统里到底有哪些中文字体Linux 和 macOS 上用fc-list :langzh family输出会列出所有支持中文的字体族名。这里要特别注意写在\setCJKmainfont{}里的是字体族名不是文件名。常见报错The font simsun cannot be found十有八九是名字写错了fc-list查出来的可能是“SimSun”或者“宋体”大小写和写法都得对上。Windows 上还有一个细节系统字体名有中文和英文两套SimSun和“宋体”指向同一个字体。ctex 的windows字体集用的是英文名一般不需要手动改。如果你自己指定建议统一用英文名避免编码问题。4.4 编译引擎选 xelatex 还是 lualatex两者都支持 Unicode 和系统字体都能处理中文区别在实现路径和生态。XeLaTeX 走的是 TeX 引擎加外部字体接口的路线成熟稳定ctex 对它的支持最完整绝大多数中文模板都是按 xelatex 调通的。编译速度中等遇到复杂宏包偶有兼容问题。LuaLaTeX 把 Lua 解释器嵌进了引擎可以在文档里写脚本处理复杂排版逻辑、动态生成内容的能力更强字体处理也更现代。缺点是部分老宏包在它下面跑不通编译速度通常比 xelatex 慢一些。我的建议很直接没有明确理由就用 xelatex。你写论文、写报告、写简历xelatex 足够遇到问题的概率最低网上能找到的解决方案也最多。只有当你要用某些依赖 Lua 特性的宏包比如某些高级绘图或数据处理包时才切到 lualatex。切换引擎不是改一个字母那么简单整条编译链都得跟着换xelatex main.tex biber main xelatex main.tex xelatex main.tex文献相关的项目要跑四遍——第一遍生成 auxbiber 读 aux 生成 bbl第三遍把文献编进去第四遍把引用编号和目录页码填正。手工敲这些命令太累用 latexmk 一条命令搞定这个在 5.2 节讲。5. 编辑器侧配置把写、编、看串成一条线5.1 LaTeX Workshop 的核心配置项编辑器选什么是个见仁见智的事专用编辑器开箱即用通用编辑器加插件灵活度高。我这些年固定在 VS Code 加 LaTeX Workshop 这套组合上原因是它同时能写代码和写文档不用在两套界面之间切换。它的配置都放在settings.json里改动会即时生效不用重启。最核心的几类配置工具定义latex-workshop.latex.tools告诉插件有哪些可调用的命令、参数是什么。这是整份配置的地基写错了后面全乱。编译流程latex-workshop.latex.recipes把工具按顺序串成一条流程比如“xelatex → biber → xelatex → xelatex”。默认流程latex-workshop.latex.recipe.default设为first表示用列表里的第一条也可以填流程名。自动编译latex-workshop.latex.autoBuild.run可选onSave保存时编译、onFileChange改了就编译、never只手动触发。写长文档时用onSave比较合适onFileChange会在你每敲一个字都可能触发机器性能一般的话会很卡。PDF 查看方式latex-workshop.view.pdf.viewertab是在编辑器标签页里内嵌显示external是调外部阅读器browser是丢到浏览器里。清理策略latex-workshop.latex.autoClean.run编译完自动删掉辅助文件。新手建议设成never因为辅助文件里的.log是排查问题的唯一依据自动删掉等于把病历本扔了。等文档稳定了再开。5.2 工具链 recipe 的写法与常见错配一份能用的配置长这样直接贴进settings.json{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] }, { name: biber, command: biber, args: [%DOCFILE%] }, { name: latexmk-xelatex, command: latexmk, args: [ -xelatex, -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], latex-workshop.latex.recipes: [ { name: xelatex - biber - xelatex x2, tools: [xelatex, biber, xelatex, xelatex] }, { name: latexmk (xelatex), tools: [latexmk-xelatex] } ], latex-workshop.latex.recipe.default: first, latex-workshop.latex.autoBuild.run: onSave }几个占位符要分清这里错一个就整条链断掉%DOC%是带扩展名的文件名main.tex%DOCFILE%是不带扩展名的main%DIR%是文件所在目录。biber 的参数要用%DOCFILE%因为它的输入约定是不带扩展名写成%DOC%会报找不到文件——这个错我见过不止一次报错信息是Cannot find main.tex看着像文件不存在实际上是参数写错了格式。-synctex1这个参数必须加它生成.synctex.gz文件正向反向跳转全靠它。-file-line-error让报错信息直接带上文件名和行号点一下就能跳到出错位置比自己在日志里翻快得多。-interactionnonstopmode前面提过防止编译卡在交互提示上。至于用 recipe 还是用 latexmk我的实际经验是短文档、流程简单的recipe 直观可控长文档、多文件、有文献有索引的latexmk 更省心它自己会分析依赖关系决定跑几遍你只管保存。5.3 外部 PDF 阅读器与正反向同步内嵌 PDF 预览方便但有两个硬伤一是大文档翻页卡二是有些阅读习惯比如同时开两个文档对比满足不了。所以不少人配外部阅读器这就涉及正反向同步。正向同步是从源码跳到 PDF 对应位置。在 VS Code 里默认快捷键是CtrlAltJ前提是编译时加了-synctex1且阅读器支持这个协议。反向同步是在 PDF 里双击某个位置跳回源码中对应的那一行。这一步需要在阅读器里配置启动命令。SumatraPDF 的设置路径是菜单里打开“设置 → 选项”找到“反向搜索命令行”填入编辑器安装路径\Code.exe -g %f:%l%f是文件路径%l是行号-g是跳转参数。填完保存在 PDF 里双击就能跳回来。macOS 上用 Skim在“偏好设置 → 同步”里选自定义命令思路一样。Linux 上常用的 zathura 支持启动参数zathura --synctex-editor-command code -g %{input}:%{line} main.pdf注意反向同步不生效九成是因为编译时没加-synctex1或者阅读器的路径里含空格但没有正确引号包裹。第二条在 Windows 上特别常见Program Files这种带空格的目录必须整个用双引号包起来否则命令被拆成两段执行失败。5.4 多文件项目与输出目录文档一长单文件就难以维护了几百行的导言区加几千行正文混在一个文件里找什么都费劲。标准做法是拆% main.tex \documentclass[UTF8]{ctexart} \input{preamble} \begin{document} \include{chapters/intro} \include{chapters/method} \include{chapters/result} \bibliography{refs} \end{document}\input是原样插入\include会另起一页并生成独立的 aux 文件适合章一级的拆分。注意\include的文件名不要带.tex扩展名。拆完之后编译主文件就行latexmk 会自动跟踪\input和\include的依赖子文件改了它也知道要重编。用 recipe 方式的话插件也能识别依赖关系但不如 latexmk 稳。输出目录是另一个容易出问题的地方。默认所有中间文件堆在源码目录里几十个.aux、.log、.out混在一起看着头疼。可以指定输出目录latex-workshop.latex.outDir: %DIR%/build或者在.latexmkrc里写$pdf_mode 5; $out_dir build;$pdf_mode 5表示用 xelatex1是 pdflatex4是 lualatex。这个映射记不住也没关系写进配置文件里一次就够。用输出目录有个副作用要注意某些宏包在找相对路径的资源时会以编译时的工作目录为准输出目录变了图片路径可能就找不到了。遇到这种情况要么用\graphicspath{{./figures/}}显式声明要么干脆不用输出目录忍一忍那一堆中间文件。6. 编译速度慢、文件找不到几个反复出现的坑6.1 路径里的空格与中文字符这个问题前面提过几次因为它出现的频率实在太高而且表现极其迷惑。你可能会遇到本机能编译换台机器就报I cannot find file或者 PDF 能生成但插图全部丢失。根源在于很多底层工具是几十年前写的处理路径拼接时用的逻辑很简单遇到空格就当成参数分隔符遇到非 ASCII 字符就按字节处理。XeLaTeX 本身对中文路径的支持其实还行但 biber、makeindex、minted 这些外围工具就不一定了。而它们出错时报错信息通常指向资源本身而不是路径误导性极强。稳妥的做法是从根上避免项目目录用纯英文、不含空格、尽量短。比如D:\work\paper或者~/doc/thesis。文件名也一样别用“第一章 绪论.tex”这种改成ch01-intro.tex。标题里的中文放在文档内部写文件名保持 ASCII。已经踩了坑想确认是不是路径问题最简单的验证方法是把整个项目复制到D:\test这种极简路径下再编译一次。能过就是路径问题还是不行再往下查其他原因。这个二分法花一分钟能省掉半小时的瞎猜。6.2 辅助文件、缓存与杀毒软件的干扰编译失败的另一个隐蔽来源是过期的辅助文件。.aux、.toc、.out这些文件是上一次编译留下的如果文档结构做了大改比如删了章节、改了标签名旧的 aux 里还留着已经不存在的引用新的一次编译读到这些残留信息就会报奇怪的错比如“引用了不存在的标签”。标准处置流程编译报错且看不出明显原因时先清干净重编。latexmk -c # 清理辅助文件保留 PDF latexmk -C # 连 PDF 一起清掉手工清也行删掉.aux、.log、.out、.toc、.bbl、.blg、.synctex.gz、.fls、.fdb_latexmk这些后缀的文件保留.tex、.bib、图片和.cls、.sty。杀毒软件是 Windows 上另一个隐形杀手。TeX Live 完整安装有七八万个文件每次编译都要读取大量文件实时防护会逐个扫描导致编译从几秒变成几十秒甚至卡死。更糟的是某些防护策略会把生成的中间文件当成可疑对象锁住引发“文件被占用无法写入”的报错。解决办法是把 TeX Live 安装目录和你的项目目录加进防护软件的排除列表。这一步做完编译速度往往有明显提升尤其是文档里图表多、引用多的时候。还有一个跟文件系统有关的坑把项目放在云同步目录里比如自动同步的网盘文件夹。同步程序会在后台不停扫描文件变更编译时生成几十个中间文件同步程序立刻开始上传既占用带宽又可能锁定文件。写论文期间建议项目目录完全离开同步范围需要备份就手动复制或者用版本管理工具。6.3 宏包更新后文档突然编不过这个场景很打击人昨天还好好的论文今天打开一编译满屏报错。你没改任何东西那就是环境变了。可能性有两个——要么是跑了tlmgr update --all要么是别人的模板更新了而你重新拉取了。判断方法很简单看日志第一条错误涉及哪个宏包然后用 tlmgr 查它的版本历史tlmgr info biblatex输出里有版本号和安装日期还有revision编号。如果确认是刚更新过的退回上一版tlmgr restore biblatex 64982revision 号从tlmgr info的输出里拿。更彻底的做法是冻结整个环境。TeX Live 支持同时安装多个年份的版本装 2024 和 2025 并存日常用新版本重要项目用老版本。切换只需要改 PATH 顺序或者用一个脚本临时设置环境变量。这个方案的好处是彻底隔离代价是占额外的磁盘空间。对于重要项目我的习惯是在项目根目录放一个versions.txt记录当前使用的 TeX Live 年份和几个关键宏包的 revision 号。万一半年后需要重新编译照着这个文件把环境还原比对着记忆瞎试靠谱。6.4 提速的几种实际手段LaTeX 编译慢是公认的但慢到什么程度、能不能救要看具体情况。冷启动慢指的是第一次编译要加载格式文件、字体、宏包这个过程几秒钟到几十秒不等。TeX Live 有格式预生成机制.fmt文件正常情况下不需要每次重新生成。如果你发现每次编译都要等很久且日志里有preloading the plain format之类的输出说明格式文件没生成好跑一下fmtutil-sys --all重新生成。文档本身大导致的慢有几种缓解手段一是用draft模式跳过图片处理\documentclass[draft]{article}这样图片位置会显示成一个框和文件名不实际渲染编译快很多。排版调完了再切回正常模式出最终版。二是分章编译。用\includeonly{chapters/method}只编译正在写的那一章其他章的内容和页码靠上一轮的 aux 文件顶着速度提升非常明显。定稿时去掉\includeonly全量编一遍。三是把不常用的宏包去掉。导言区里堆着几十个\usepackage每个都要加载哪怕这次没用上。定期清理一下编译速度会有可见的变化。四是加-halt-on-error参数。这个不是提速而是省时间一旦出错立刻停不用等着它把后面几十页的错误全跑一遍。还有一个容易被忽略的因素Windows 上文件系统的开销。TeX Live 完整安装有大量小文件机械硬盘上随机读取很慢。把 TeX Live 和项目都放在固态硬盘上编译时间的差距是肉眼可见的。7. 从能编译到日常顺手模板、文献与版本管理7.1 模板拿过来之后要先改哪几处谁都不会从零写导言区拿现成模板是常态。但模板直接拿来用往往会出问题因为它是在作者自己的环境里调通的换台机器就未必。拿到一个模板先做三件事。第一读导言区看它依赖哪些宏包哪些是冷门的。冷门宏包意味着可能没装、可能版本不匹配。先跑一次编译把所有File xxx.sty not found收集起来一次性tlmgr install装齐。第二确认编译引擎。模板作者可能用的是 pdflatex而你按习惯用了 xelatex两者对某些宏包的兼容性不一样会报! Package xxx Error之类的错。文档类文件.cls的开头注释里通常会写推荐引擎或者在模板说明里找。找不到就看它有没有用fontspec、ctex这类只有 xelatex/lualatex 才支持的包有就说明必须用 xelatex。第三检查字体。如果模板里写死了某个字体名而你的系统里没有这个字体就会报font cannot be found。处理办法有两种装这个字体或者把字体设置改成你系统里有的。后者更现实找到\setmainfont{}、\setCJKmainfont{}这几行替换成fc-list里查得到的名字。改完之后先编译一遍看能不能过能过再去动内容。不要在编译还不通的时候开始写正文那样出了问题你分不清是环境问题还是内容问题。7.2 参考文献链路biber 与 bibtex 的分工参考文献是 LaTeX 里最容易出问题的一环因为它的工具链比正文多一层。老的一套是 BibTeX 配\bibliographystyle{}新的一套是 Biber 配biblatex宏包。两者不兼容混用会报错。用biblatex的写法\usepackage[backendbiber,stylenumeric]{biblatex} \addbibresource{refs.bib}正文里\cite{key}文末\printbibliography。编译顺序是 xelatex → biber → xelatex → xelatex。用传统 BibTeX 的写法\bibliographystyle{plain} \bibliography{refs}编译顺序是 xelatex → bibtex → xelatex → xelatex。关键的坑在这里biber 和 biblatex 的版本必须匹配。只更新了其中一个就会报biblatex.sty: incompatible version之类的错或者更隐蔽地编译成功但文献列表是空的。后者最难查因为没有任何报错你只是发现参考文献没出来。判断是不是版本问题看.blg文件biber 的运行日志不是.log。这个文件里记录了 biber 的版本、读到的 bib 文件、处理的条目数。文献不出来的时候.blg里的信息比.log有用得多。另一个常见问题是.bib文件的编码。早期用 GBK 保存的 bib 文件在 UTF-8 环境下中文作者名会变成乱码。用编辑器转成 UTF-8 保存即可。还有一条中文文献的作者名和标题建议在 bib 文件里用{}保护起来比如author {{张三} and {李四}}防止 biber 把中文姓名按西方规则拆成姓和名。这个细节不处理出来的参考文献格式会很怪。7.3 用版本管理守住能编译的版本LaTeX 项目的版本管理和代码项目有一个本质区别大量中间文件是生成物不该进版本库但有些“生成物”又需要保留。该忽略的.aux、.log、.out、.toc、.synctex.gz、.fls、.fdb_latexmk、.bbl、.blg。这些都是编译产物能从源文件重新生成。不该忽略的.bib、.cls、.sty如果是模板自带的、所有图片、.tex源文件。有人把.bbl也忽略了这在纯本地环境下没问题但如果要把项目发给别人或者上传到提交系统很多系统只接受带.bbl的包因为它不一定会跑 biber。所以对外提交前手动编译一遍把.bbl生成出来一起打包。.gitignore大致这么写*.aux *.log *.out *.toc *.synctex.gz *.fls *.fdb_latexmk *.blg build/还有一个实践值得推荐每次论文改到一个阶段性节点打一个 tag。投稿前、返修前、终稿前各打一个。LaTeX 项目最怕的就是“改着改着发现三天前那版更好但已经回不去了”。有了 tag随时能检出历史版本重新编译出 PDF。如果不用版本管理至少做到每天结束时把整个项目目录复制一份带日期的备份。听着土但真出事的时候能救命。我见过硬盘故障丢掉整篇论文初稿的情况那种绝望没必要体验第二次。一个额外的建议把编译出来的 PDF 也纳入版本管理或者单独存一份归档。因为源码能编译出 PDF 的前提是环境一致而环境会变。存一份当时编译出的 PDF等于存了一份“当时长什么样”的铁证日后核对格式问题时非常有用。我自己这些年用下来最深的体会是环境这件事值得一次做对。刚开始图快装个精简版、随便找个模板、编辑器里瞎点后面会在各种莫名其妙的地方还债——今天缺个宏包明天字体找不到后天编译卡死。花两个小时按部就班装个完整版、把 PATH 配好、把中文字体理顺、把编辑器链路调通后面几年都省心。真遇到编译不过的时候先别急着改代码从日志第一条!开始看八成问题都出在环境或者路径上而不是你写的那几行。
