MikTeX 装完那一刻很多人会以为事情结束了一半结果把拿到的中文 PPT 模板往编辑器里一丢按下编译屏幕上滚出一片红字。我见过太多次这种场面模板来自某个资源站压缩包里躺着 .tex、.cls、.sty、一两个 logo 图片README 只有一行用 XeLaTeX 编译。问题就出在这行字上——它默认你已经知道该改哪里、该装什么、该避开什么。这篇东西面向三类人刚装完 MikTeX 想跑通第一个中文演示文稿的新手、手上有现成 beamer 模板但总是编不过去的同学、以及想把 LaTeX 当作日常做汇报 PPT 工具的职场人。完整走完一遍你会得到一条从安装、字体配置、模板改造、编辑器接线到排错的完整链路最后能稳定产出一个可以直接拿去投影的 PDF。中间那些报错为什么会出现、为什么这样改就能好、哪些地方看起来修好了其实埋了雷我都会讲清楚。1. 中文模板在 MikTeX 上翻车的三个断点绝大多数编译失败并不是一个错误而是三个独立故障叠加在一起被日志揉成了一团。你只有把这三点拆开看才知道每次改动是不是真的在往前走。1.1 第一断点默认编译器选错pdfLaTeX 死在字符集上新装的 MikTeX 不带编辑器但不管你后面用 TeXstudio、TeXworks 还是 VS Code默认的编译命令大概率是pdflatex。pdfLaTeX 诞生在上世纪八十年代它的设计前提是输入里全是 ASCII。一个中字对它来说就是 U4E2D 这个码位它根本不知道该怎么把它变成字形。于是你看到的是这条! Package inputenc Error: Unicode character 中 (U4E2D) (inputenc) not set up for use with LaTeX.这条报错非常容易误导人。字面意思像是inputenc 没配好于是有人去翻\usepackage[utf8]{inputenc}的文档加参数、换编码怎么改都没用——因为这个宏包在 pdfLaTeX 下能做的只是把字节映射到有限的字形表汉字压根不在那张表里。注意在 XeLaTeX 下\usepackage[utf8]{inputenc}会被直接忽略并给一条 warning不会报错所以模板里留着它通常无害。真正致命的是用 pdfLaTeX 去跑它。正确的做法不是改 inputenc而是换引擎。XeLaTeX 原生按 Unicode 处理输入调用系统字体是中文 LaTeX 的首选LuaLaTeX 同样支持但字体缓存和宏包兼容性上的坑更多一些。本文后面所有配置都以 XeLaTeX 为准。1.2 第二断点字体名对不上换了引擎还是白纸换成 XeLaTeX 之后很多人会进入一个更迷惑的状态编译通过了日志没有 Error但导出的 PDF 里中文全是空白或者变成一排方框。这不是玄学是字体没找到。XeLaTeX 处理中文一般走xeCJKctex宏包会自动加载它它需要一个真实的字体文件和一个字体名。字体名分两种一种是 PostScript 名比如SimSun、SimHei、KaiTi另一种是文件路径比如C:/Windows/Fonts/simsun.ttc。ctex的fontsetwindows选项会去调用前者这在标准 Windows 上没问题但如果你在精简版系统、改了字体库、或者虚拟机里跑字体名就可能对不上。关键是字体找不到的时候 xeCJK 不一定报错。它可能只是安静地跳过直到xdvipdfmx阶段才丢一句xdvipdfmx:fatal: Unable to find TFM file SimSun.或者更含蓄的一条Package fontspec Warning: Font SimSun does not contain requested Script CJK.所有字体类问题第一件事是打开.log文件用编辑器搜Font、fontspec、xdvipdfmx三个关键词。命令行里滚过去的信息经常被截断.log才是完整真相。1.3 第三断点缺宏包被静默吞掉或者装到一半卡住第三个断点是宏包。模板作者在一台装满宏包的机器上写的\usepackage{tikz}、\usepackage{pgfplots}、\usepackage{fontawesome5}你的 MikTeX 里可能一个都没有。MikTeX 有个很贴心的设计叫按需安装宏包install missing packages on-the-fly第一次遇到缺失的包会联网下载。但它的默认行为是先问我Ask me first会弹一个对话框。如果你是在编辑器里编译这个对话框可能被主窗口挡住表现出来就是编译卡住不动进度条一直转。如果你在命令行里编译它就静静地等在那儿。比卡住更麻烦的是只装了一半。网络抖一下下载中断宏包目录里留下一个残缺的包之后每次编译都从这里开始报错你还以为是模板本身有问题。所以安装完 MikTeX 后第一件事就是进控制台把这三个开关调好。具体调什么、在哪里调下一节讲。断点典型现象表面误导真正的处理方向编译器Unicode character 中 ... not set up像是编码配置问题换成 XeLaTeX不要动 inputenc字体中文空白、方框、TFM 文件找不到像是模板坏了检查字体名与 fontset必要时改用文件路径或 Fandol宏包编译卡住、报File xxx.sty not found像是网络或磁盘问题改自动安装策略手工补装缺失包并刷新文件名数据库这三个断点有个共同点它们都会把错误往下游推让真正的病因出现在离现场很远的地方。理解了这一点后面看日志的时候就不会被带偏。2. MikTeX 安装包的取舍与控制台里必须改掉的项目安装这一步看起来最没技术含量实际上它决定了你后面调试的难度。选错安装包后面每次遇到新模板都要联网等下载选对路径能省掉一批莫名其妙的权限报错。2.1 网络安装器还是完整安装包官网给的选择通常有两个体积小的网络安装器安装时按需下载和体积大的完整安装包自带绝大部分宏包。单看省空间网络安装器很划算。但如果你接下来的主要工作是反复试各种来源的模板我建议直接上完整安装包。理由很实在网络安装器的按需下载在第一次编译陌生模板时可能要拉几十个宏包遇到国内的网络环境一次编译三分钟里有两分半在等下载而完整安装包一次性把常用宏包铺垫好后面就是纯本地编译速度快一个量级。反过来如果你只是偶尔编一次文档机器空间紧张网络安装器也完全够用只要把后面 2.3 里的自动安装策略改成总是安装就行。2.2 安装在哪个位置以及为谁安装MikTeX 有两种安装范围仅为当前用户安装默认落在%LOCALAPPDATA%\Programs\MiKTeX这类用户目录下不需要管理员权限。为所有用户安装落在C:\Program Files\MiKTeX需要管理员权限。如果你在这台机器上只有自己的账号选前者省事且不会触发权限问题。如果你要给实验室或团队的多个账号共用选后者。不要混着来有些人在用户目录装了一份后来又用管理员权限装了一份结果 PATH 里指着一个、编辑器里配的是另一个宏包的安装和读取分属两个仓库报错信息会非常难解释。还有一条几乎所有人都踩过的坑项目和输出路径不要带中文和空格。MikTeX 本体对这些字符的处理已经不错了但整条工具链里还有 biber、makeindex、gnuplot 这些外部程序它们的参数解析器可没这么宽容。给自己定个规矩所有 LaTeX 项目放在D:\tex\项目名这类纯英文路径下能省掉一大类无法复现的诡异故障。2.3 控制台里必须调整的几个设置装完之后打开 MiKTeX Console重点在这个面板第一项包安装策略。在 Settings 里找到安装缺失的宏包Install missing packages on-the-fly把它从Ask me first改成Yes。这一项改完编辑器里编译陌生模板时就不会再被隐藏对话框卡住。第二项仓库镜像。在 Packages 页面里可以切换远程仓库。默认走官方源国内地址下载速度可能很慢。换成地理位置更近的镜像按需下载的体验会好很多。切换后先刷新一次包列表。第三项默认纸张。Settings 里的默认纸张尺寸设成 A4。MikTeX 的默认值在不同版本里可能是 Letter而中文模板基本都是按 A4 排的边距和分页会整体偏移。第四项做完安装或更新后刷新文件名数据库。在 Tasks 里能找到Refresh file name database。这一项在两种情况下必须手动执行一是你手工往texmf目录里丢过文件二是大批量更新宏包之后。文件名数据库没刷新就会出现文件明明在磁盘上编译器却说找不到的情况非常消耗排查时间。命令行等价操作initexmf --update-fndb2.4 手工补装宏包的两种方式有时候自动安装会失灵尤其是模板里引用了比较冷门的包或者包名写错了。这时手工补装miktex packages install ctex老版本 MikTeX 用的是另一套命令mpm --installctex怎么判断该装哪个包从.log里搜not found标准格式是! LaTeX Error: File xxx.sty not found.其中xxx就是要装的包名。绝大多数情况下包名和\usepackage{xxx}里的名字一致少数例外比如\usepackage{tikz}对应的是pgf包这时候用控制台的搜索功能按文件名反查会更稳。提示一次安装大量宏包后不要立刻去编译复杂模板先在控制台做一次Refresh file name database和一次包更新检查把状态收敛干净再动手。3. 把中文接进 beamer两条路线与字体落地MikTeX 环境就绪之后才轮到模板本身。中文 beamer 模板的接入方式只有两条路线认准是哪条改动量能小一半。3.1 路线一直接用 ctexbeamer 文档类如果模板主文件第一行长这样\documentclass[UTF8,aspectratio169]{ctexbeamer}那它走的是路线一。ctexbeamer是ctex宏包体系给 beamer 提供的封装文档类它会自动处理中文断行、标点挤压、字体集、hyperref的中文书签等一整套东西你几乎不用额外配置改完字体集就能编译。这条路线最省心问题也最少。如果模板已经是这个形式直接跳到 3.3 调字体即可。3.2 路线二beamer 加 ctex 宏包以及最常见的冲突更多模板长这样\documentclass[aspectratio169]{beamer} \usepackage[UTF8]{ctex}功能上和路线一基本等价但顺序和选项有讲究。常见冲突有三种第一种模板里已经有\usepackage{CJKutf8}或\begin{CJK}{UTF8}{gbsn}环境。这是 pdfLaTeX 时代的写法在 XeLaTeX 下虽然能跑但字体渲染质量差而且在 beamer 的 frames 环境里嵌套容易出问题。处理方式是删掉CJKutf8相关代码把整个 CJK 环境去掉改用ctex宏包接管。第二种模板加载了旧的字体宏包。比如\usepackage{mathptmx}、\usepackage{times}、\usepackage{txfonts}。这类宏包会把数学和正文字体整个替换掉和xeCJK的字体设置打架表现出来就是英文正常、中文错位或者行距异常。保留数学字体需求的话换成fontspecunicode-math的写法更稳妥。第三种宏包顺序导致\xeCJKsetup不生效。ctex要在绝大多数宏包之前加载尤其是hyperref之前。见到模板里hyperref排在ctex前面直接调换顺序。注意改模板之前先原样复制一份留底。中文模板的故障经常是改了三处好了但不知道是哪一处起作用留底能让你在下一份模板上少走弯路。3.3 fontset 选项与字体真正落地ctex通过fontset选项决定用哪套中文字体可选值包括windows、fandol、adobe、ubuntu、macnew、none等。在 Windows 上默认是windows也就是调用系统里的宋体、黑体、楷体、仿宋。问题在于windows字体集依赖系统字体完整。如果你的机器上做过字库精简或者你在别人的机器上编译就会踩到 1.2 里说的字体找不到。这里给两个方案按场景选方案 A坚持用系统字体但显式指定字体名。直接写清楚用哪个字体避免ctex猜错\usepackage[UTF8,fontsetnone]{ctex} \setCJKmainfont[BoldFont{SimHei},ItalicFont{KaiTi}]{SimSun} \setCJKsansfont{Microsoft YaHei} \setCJKmonofont{FangSong}方案 B换成 Fandol 字体集。Fandol 是一套开源中文字体随 TeX 发行版分发不依赖系统字库跨机器编译时表现一致\documentclass[UTF8,fontsetfandol]{ctexbeamer}用 Fandol 的前提是本地装了fandol宏包。MikTeX 上一开始没装的话自动安装会拉下来如果自动安装失败就手工补miktex packages install fandol代价是 Fandol 的字形偏瘦投影效果不如微软雅黑、思源黑体这类现代黑体。做汇报用的幻灯片我个人更推荐方案 A 配合带 Bold 的现代字体具体在 4.4 讲。3.4 一个能跑起来的最小可编译文件在动复杂模板之前先建一个最小文件验证环境。这一步的价值在于如果最小文件都编不过问题一定在环境和配置上跟模板无关。\documentclass[UTF8,aspectratio169]{ctexbeamer} \usetheme{Madrid} \title{中文演示文稿编译验证} \author{测试} \date{\today} \begin{document} \begin{frame} \titlepage \end{frame} \begin{frame}{测试页} \begin{itemize} \item 这是一行中文用于验证字体是否正确加载。 \item 下面是一行包含中英文混排的内容LaTeX 与 MikTeX 配合 XeLaTeX。 \item 标点测试逗号句号。顿号、分号冒号问号 \end{itemize} \end{frame} \end{document}用一个带-interactionnonstopmode的命令行方式跑一遍把完整日志留在眼前xelatex -interactionnonstopmode -synctex1 test.tex看到 PDF 里中文正常显示、标点位置正常、没有方框就可以拿真实模板来做改造了。这个最小文件建议一直留着后面换电脑、换版本时它就是你的体温计。4. 中文幻灯片的排版调优断行、标点、字重与公式编译通过只是及格线。中文幻灯片真正难的地方在于看起来正常——字与字的间距、行末的断行位置、加粗是否生效、公式和中文混排时的基线是否打架。这些问题单看不致命堆在一起就是这个 PPT 有点糙的观感。4.1 中文断行为什么你的行末总是空一大块中文没有空格断行规则和英文完全不同。如果断行机制没生效XeTeX 会把一整段中文当成一个超长单词结果是整段冲出画布或者被迫在很不自然的位置断行。xeCJK正常加载时会自动设置断行规则不用你操心。但如果你遇到两种情况就要手动补一是模板显式关掉了自动设置二是用了fontsetnone又没走ctex的完整流程。这时候在主文件导言区补上\XeTeXlinebreaklocale zh \XeTeXlinebreakskip 0pt plus 1pt minus 0.1pt第一行告诉引擎按中文规则找断点第二行给出可伸缩的胶合量让引擎在两端对齐时有微调空间。少了第二行中文行末容易出现生硬的大片空白。4.2 标点挤压与行首行末禁则中文排版有一条基本规则句号、逗号、顿号不能出现在行首左引号、左括号不能出现在行末。这件事在xeCJK里由\punctstyle控制\xeCJKsetup{PunctStylequanjiao}quanjiao是全角标点也是中文排版的默认风格。可选值还有banjiao半角、kaiming开明式标点占半角宽度但不删空格、plain不做任何调整。什么时候要改如果你做的模板是偏紧凑的商务风格标题区一行字很多quanjiao会让标点周围留下明显空隙观感偏松。可以针对标题单独设成kaiming正文保持quanjiao。反过来plain基本不要用它等价于放弃中文标点规则行首出现逗号会很扎眼。4.3 公式与正文混排时的中文字体切换中文技术类演示文稿经常要在公式里塞中文比如$E_{\text{总}}$。这里有两个坑。第一个坑是\text{}里用的是当前数学字体的文本模式如果数学字体没设好中文可能变成方框。稳妥的写法是用\mbox{}或者直接在主字体已经正确的情况下用\text{}并且确保amsmath已经加载。第二个坑是unicode-math与ctex的配合。unicode-math会接管数学字体如果它加载在ctex之前中文字体设置可能被重置。顺序上让ctex先来\usepackage[UTF8]{ctex} \usepackage{amsmath} \usepackage{unicode-math}如果模板本身不用unicode-math直接用默认的数学字体就够不必为了看起来现代去加它多一个宏包就多一层潜在冲突。4.4 投影场景下的字重与字号取舍这一条是从实际使用里总结出来的文档里基本不会写。幻灯片和打印文档的阅读条件完全不同。打印文档靠得近笔画细一点不影响投影是在几米外看笔画细的字体在投影仪上会发灰、发虚。ctex的windows字体集里正文默认是宋体。宋体是印刷体不是投影体。做汇报用建议把正文和标题统一换成黑体系列。改法是在导言区重设\setCJKmainfont[BoldFont{Microsoft YaHei Bold},ItalicFont{KaiTi}]{Microsoft YaHei}这里有个细节值得展开Windows 自带的SimHei黑体只有一个字重没有 Bold。而 beamer 的标题、\textbf{}、\alert{}都依赖粗体。当字体没有 Bold 时xeCJK不会报错它只是假装加粗或者干脆不加粗结果是标题和正文看起来一样粗层级完全丢失。两个解法用带真粗体的字体比如微软雅黑有 Regular 和 Bold 两套或者思源黑体。让xeCJK做伪粗\setCJKmainfont[AutoFakeBold2.5]{SimHei}AutoFakeBold的数值是膨胀量2 到 3 之间比较自然。数值太大会让笔画粘连小字号下尤其明显。伪粗的观感不如真粗但如果模板已经确定用黑体这是最省事的补丁。使用场景推荐中文字体字重策略注意点投影汇报标题微软雅黑 / 思源黑体用真 Bold微软雅黑 Bold 需系统已安装投影汇报正文微软雅黑 Regular不加粗字号不低于 20pt 才够看打印讲义宋体 / 思源宋体标题用黑体区分行距适当加大数学公式内中文与正文同字体继承正文避免在公式里切换字族还有一个容易被忽略的点beamer 的\frametitle默认字号有限中文标题一长就会挤成两行甚至溢出。可以在导言区调整\setbeamerfont{frametitle}{size\large,series\bfseries}遇到长标题宁可拆成主副标题两行也不要把字号一路压小投影上会看不清。5. 编辑器接线与一键编译链路MikTeX 本身没有好用的编辑器。把编译命令接进编辑器才能摆脱在命令行里反复敲xelatex的循环。这里给两套方案TeXstudio 适合专心做 LaTeX 的人VS Code 适合同一台机器上还要写代码的人。5.1 TeXstudio四步接好 XeLaTeXTeXstudio 的配置集中在选项 → 设置 → 构建这一页。第一步把默认编译器改成XeLaTeX。这一步不做前面所有字体和宏包的调整都白费。第二步确认 XeLaTeX 的命令行参数。默认通常是xelatex -synctex1 -interactionnonstopmode %.tex-synctex1用来生成正反向搜索信息支持PDF 里双击跳到源码和源码跳 PDF写长文档时非常省事。-interactionnonstopmode让编译遇到错误不暂停等输入这在编辑器里是必须的否则一旦出错就卡住。第三步检查 BibTeX/Biber 的配置。如果模板用了参考文献biblatexbiber的组合要走 Biber 而不是 BibTeX。TeXstudio 里两个都在构建页把模板实际用的那个填对。第四步打开显示高级选项把自动检测编译方式关掉。这个功能会去猜你该用哪个引擎猜错的概率不低在中文模板上尤其容易倒退成 pdfLaTeX。5.2 VS Code 加 LaTeX Workshop手写配方更可控VS Code 这边装 LaTeX Workshop 扩展然后打开settings.json核心是两段配置工具定义和编译配方。{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [-synctex1, -interactionnonstopmode, -file-line-error, %DOC%] }, { name: biber, command: biber, args: [%DOCFILE%] } ], latex-workshop.latex.recipes: [ { name: xelatex 单次, tools: [xelatex] }, { name: xelatex biber xelatex x2, tools: [xelatex, biber, xelatex, xelatex] } ] }这里有个很实用的参数-file-line-error。加了它日志里的错误信息会带上文件名和行号格式是文件:行: 错误VS Code 的终端能直接识别成可点击的链接点一下就跳到出问题的那一行。在几十页的演示文稿里找一行错误有没有这个参数差别巨大。另外建议把latex-workshop.latex.autoClean.onBuild关掉。自动清理中间文件看着清爽但排查问题时.aux、.log、.nav这些文件是有价值的线索被清掉就得重新编一遍才能复现。5.3 编译顺序为什么改一个字要编三遍beamer 的编译次数不是随意的跟 PDF 里哪些内容需要跨轮次信息有关。需要生成的内容至少需要的编译轮次用到的中间文件正文更新1 次 xelatex.aux目录与页码2 次 xelatex.toc、.aux参考文献Biberxelatex → biber → xelatex → xelatex.bcf、.bbl导航栏与书签2 次 xelatex.nav、.snm、.out原因在于第一遍编译时引擎会把目录项、页码、引用编号这些暂时还不知道的值写进辅助文件并留一个占位第二遍读回辅助文件才能把真实数字填进去。所以只改了正文文字编译一遍就够改了章节结构、加了引用、动了参考文献就必须跑完整链路。嫌麻烦的话用latexmk统一调度它会自动判断需要跑几遍latexmk -xelatex -synctex1 -interactionnonstopmode main.tex在 LaTeX Workshop 里也可以把latexmk包成一个 recipe日常就用它不用管轮次。5.4 中间文件清理与哪个文件能删频繁编译会攒下一堆中间文件。哪些能删、哪些不能删给个对照可以随时删.aux、.log、.nav、.snm、.out、.toc、.bbl、.bcf、.run.xml、.synctex.gz。删掉后重新编译会再生成代价是多编译几遍。不能删.tex、.cls、.sty、模板自带的图片和字体目录、.bib文献库。谨慎删模板里附带的.pdf。有些模板把 logo 或示例图存成 PDF 放在项目里删了会导致图片找不到。批量清理可以用命令行在项目目录下执行latexmk -c它只删中间文件不动源码和最终 PDF。想连 PDF 一起删用latexmk -C。6. 六类高频报错的完整排查链路前面讲的都是怎么配这一节讲出错之后怎么找。我把遇到频率最高的六类问题按排查顺序列出来每一类都给出从现象到根因的完整路径而不是直接甩答案。6.1 找不到 ctex.sty自动安装为什么会失灵! LaTeX Error: File ctex.sty not found.看到这条第一反应通常是宏包没装于是去控制台搜 ctex 装上重新编译还是同一条。这时候要分三步查第一步确认控制台里真的装上了。在 MiKTeX Console 的 Packages 页面搜ctex看状态是 Installed 还是 Not installed。如果显示已安装但仍报错往下走。第二步刷新文件名数据库。在 Tasks 里执行Refresh file name database或者命令行initexmf --update-fndb。刚装完的宏包没进数据库编译器按名字索引是找不到的。第三步检查是不是有多个 MikTeX 实例。在命令行执行where xelatex看看输出几条路径以及是不是和你编辑器里配置的那份一致。用户级安装和全局安装共存时宏包装进了 A编译走的是 B这条命令能立刻暴露问题。还有第四种可能宏包确实装了但装在一个不被搜索的texmf树里。手工往texmf目录丢过文件的话记得执行一次initexmf --update-fndb让索引重建。6.2 字体找不到从字体名到文件路径的降级方案Package fontspec Error: The font SimSun cannot be found.这类错误的排查链条是先确认字体在不在系统里再确认名字对不对最后考虑降级到文件路径。确认字体存在。打开C:\Windows\Fonts搜simsun看有没有simsun.ttc。精简系统里宋体被裁掉是常见情况。确认名字对不对。字体名不是文件名。simsun.ttc里可能包含 SimSun 和 NSimSun 两个字体名。想确认准确名字Windows 上可以打开设置 → 字体点进具体字体看详细信息或者用fc-list命令如果装了 fontconfig 工具。名字错一个字母fontspec就找不到。降级到文件路径。名字这条路走不通直接写文件\setCJKmainfont[ Path C:/Windows/Fonts/ , BoldFont simhei.ttf , ItalicFont simkai.ttf ]{simsun.ttc}要注意两点Path结尾的分隔符用正斜杠Windows 的反斜杠在 LaTeX 里是转义字符另外Path后面和文件名前面都有空格是为了拼接时不出错别删。最后的降级方案是换字体集。把fontset改成fandol用开源字体兜底至少能保证编译通过交付出去不会因为别人机器上没这个字体而炸掉。6.3 中文不显示也不报错最阴的一类故障还有一种情况最消耗耐心日志里一个 Error 都没有只有几条 warningPDF 也生成了但中文位置是空的或者是一排实心方块。排查顺序先看 PDF 里是空白还是方框。方框说明字体加载了但缺字形空白说明压根没渲染。这是两条不同的路径。搜日志里的Missing character。如果看到大量Missing character: There is no 中 in font ...说明用的是fontsetnone又没设\setCJKmainfont或者设了一个不含中文的字体比如误设成 Arial。顺着日志里那个字体名往回找就能定位到是哪一行设置出的问题。检查有没有被\CJKfamily掩盖。有些老模板会在某些 frame 里临时切换字族切到了一个不存在的字族中文就凭空消失。搜源码里的\CJKfamily、\heiti、\songti、\kaishu这些命令看用到的字族有没有在导言区定义。最后检查\setCJKmainfont有没有被后面的设置覆盖。模板通常在导言区后面还会有一段自定义如果那里又设了一次字体前面的就白设了。搜索整个导言区里setCJK出现的所有位置以最后一次为准。6.4 写不进去PDF 被占用导致的编译中断! I cant write on file main.pdf.这条报错的根因往往简单到让人恼火你的 PDF 阅读器正开着这个文件。Windows 上文件被占用时其他程序无法写入xelatex在生成 PDF 的最后一步失败。排查动作关掉 PDF 阅读器尤其是 Adobe Acrobat、福昕这类会常驻后台的重新编译。如果关了还报同样的错往下查三层文件被同步盘锁定。项目放在某网盘的同步目录里同步进程正在读取这个 PDF导致文件被占用。杀毒软件实时防护。少数安全软件会在文件写入瞬间做扫描短暂锁定。把项目目录加进排除列表。权限问题。项目被放在了受保护目录比如系统盘根目录下某些位置当前账号没有写入权限。把项目移到用户目录下的工作区。这个坑的特点是可复现性差——报错时有时无看起来像随机故障实际原因非常确定。记住先关阅读器这个反射能省下大量时间。6.5 参考文献相关Biber 与 biblatex 的版本错配Package biblatex Error: File main.bbl not created by biber.或者biblatex.sty: ... incompatible versionbiblatex宏包和biber程序必须版本匹配而 MikTeX 的更新是增量的容易出现宏包更新到新版而biber还是旧版的情况。处理方式很直接打开 MiKTeX Console执行一次全面更新Updates 页面全选后更新让两者对齐。更新完成后刷新文件名数据库再重新编译。另一个高频原因是编译链路上没用 Biber。如果模板里写的是\usepackage[backendbiber]{biblatex} \addbibresource{refs.bib}那编译流程里必须插入biber main这一步位置上在第一次 xelatex 之后、第二次 xelatex 之前。用 TeXstudio 的话检查构建页里 Biber 是否启用用 VS Code 的话就是 5.2 里的那套 recipe。6.6 目录与书签乱码超链接设置和tocloft的冲突生成的 PDF 里正文目录正常但阅读器侧边栏的书签是乱码或者目录的超链接跳到错误的页。书签乱码一般出在hyperref的 Unicode 选项上。XeLaTeX 下通常不需要额外设置但如果模板用的是 pdfLaTeX 时代的配置可能会显式关掉 Unicode 书签\usepackage[unicodefalse]{hyperref}把unicodefalse去掉或者改成unicodetrue。XeLaTeX 下hyperref会自动处理编码一般不用显式写这个选项。目录超链接跳错位置基本都是编译轮次不足导致的。目录项的页码是上一轮编译的残留跑完整的两遍 xelatex 就好。tocloft与 beamer 冲突是另一类。tocloft是给article、book文档类调整目录样式的宏包beamer 自己有目录机制两者一起加载会互相覆盖。如果模板里出现\usepackage{tocloft}尝试注释掉看目录是否恢复正常。排查这类问题的通用方法是二分法把可疑的\usepackage一行行注释掉每注释一行编一次看什么时候恢复正常。虽然慢但在宏包冲突这类问题上比读文档快得多。习惯之后一次注释三五行两三轮就能锁定。7. 出 PDF 之后的检查与模板复用编译成功不等于交付成功。特别是这份 PDF 要发给别人、要在会场的机器上放映的时候还有几项检查值得花五分钟。7.1 画布比例16:9 与 4:3 的实际影响现在的投影仪基本都是 16:9但不少中文模板还停留在 4:3 时代。画布比例不对放映时要么两侧留黑边要么被拉伸变形。beamer 里控制比例的是文档类选项\documentclass[UTF8,aspectratio169]{ctexbeamer}169是 16:943是 4:3还有161016:10和323:2。注意不能随便改有些模板的配色和标题栏布局是按某一个比例调好的改成 16:9 之后装饰元素会错位。如果模板本身没有加aspectratio选项说明它用的是默认的 4:3改动前先看看标题页和章节页有没有用绝对坐标定位的图形。判断方法很简单编译出来看第一页有没有黑边或者用 PDF 阅读器的属性面板看页面尺寸。16:9 的常见尺寸是 362.8mm × 204.1mm 左右。7.2 字体嵌入检查与跨机器分发的坑要发给别人的 PDF必须确认所有字体都已嵌入。没嵌入的字体在你机器上显示正常到别人机器上就变成替代字体中文排版会散架。检查方式两种一是用 PDF 阅读器的文档属性看字体页每个字体后面应该标着已嵌入或嵌入子集。出现未嵌入就要处理。二是用命令行工具pdffontspoppler 工具集里的pdffonts main.pdf输出表格里的emb列yes表示已嵌入no就是没嵌入。XeLaTeX 生成的 PDF 默认会嵌入用到的字体子集正常情况下不用操心。出现没嵌入的情况通常是用了系统里某个受限字体或者字体本身禁止嵌入。解决办法就是换字体别在这上面折腾。顺带一提Windows 的微软雅黑、宋体在跨平台分发时是有授权限制的做公开材料或者商业用途的演示文稿字体选择上要留个心。开源字体思源黑体、思源宋体、Fandol在这类场景下更省事。7.3 一套内容多套主题的复用方式如果你打算长期用 LaTeX 做汇报值得花点时间把内容和样式拆开。做法是建一个style.tex把所有和外观有关的东西都放进去主题、配色、字体、字号、页眉页脚、标题样式。主文件里只留内容\documentclass[UTF8,aspectratio169]{ctexbeamer} \input{style} \begin{document} \input{content/01-intro} \input{content/02-method} \input{content/03-result} \end{document}这样换一套外观只改style.tex一个文件内容一行都不用动。做不同场合的汇报——组会、答辩、客户演示——准备三份style就够了。拆分时有一个坑值得提醒\input引入的子文件里不要放\documentclass和\begin{document}也不要在子文件里放\usepackage。宏包加载必须在导言区完成放到子文件里会报\usepackage ... Missing \begin{document}或者更奇怪的错误。子文件里只写内容和该文件专用的宏定义。还有一个细节\input和\include的差别在 beamer 里被放大了。\include会强制分页在 beamer 里就是强制开新的一帧经常导致多出空白页。做幻灯片拆文件一律用\input。最后说一点个人体会。中文 LaTeX 演示文稿的调试八成的痛苦来自不知道自己改的那一处到底有没有生效。所以我的习惯是每调一个变量就编一次改字体就单独编一次改断行设置就单独编一次绝不一次性改五处再编译。看起来慢实际比在五处改动里做归因快得多。另外那个最小可编译文件我到现在还留在工作目录里每次换机器、升级 MikTeX、装新版本都先拿它跑一遍确认环境没问题了再碰真实项目。这个习惯帮我挡掉了至少十几次以为是模板的问题其实是环境的问题。