跳转至

常见问题与排错指南

即使是经验丰富的物理学者，在撰写包含大量公式与长篇文献的 LaTeX 文档时，也难免遇到编译报错．许多初学者常因看到终端中滚动的几十行英文日志而感到焦虑，甚至放弃使用．

实际上，LaTeX 的排错逻辑与编程调试完全一致：绝大多数错误都遵循固定的模式，并且日志中已经给出了精确到行号的明确线索．本页面为你总结了读懂编译日志的技巧、物理写作十大高频报错急救方案，以及物理排版红黑榜．

如何高效阅读 LaTeX 编译报错日志

当 VS Code 弹出 Recipe terminated with error 提示时，不要慌张，按以下三步快速定位核心问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
+--------------------------------------------------------------------------+
| VS Code 终端 / 输出面板 (LaTeX Compiler Log)                              |
|                                                                          |
|  ... (前面几百行加载宏包的普通信息，直接忽略)                                 |
|                                                                          |
|  ! Undefined control sequence.              <--- 1. 寻找核心感叹号 !        |
|  <recently read> \bm                                                     |
|                                                                          |
|  l.45   \nabla \times \bm{E} = - \partial_t \bm{B} <--- 2. 锁定精准行号 l.45 |
|                                                                          |
|  ?                                          <--- 3. 产生中断的位置         |
+--------------------------------------------------------------------------+
  1. 寻找致命感叹号 !： 在输出日志中，凡是导致编译彻底终止的致命错误（Error），开头必然带有醒目的空格与感叹号 !．所有未带 ! 的信息（如 Overfull \hbox、Underfull \vbox）仅仅是排版松紧度的警告（Warning），完全不影响 PDF 文件的成功生成．
  2. 锁定精准行号 l.数字： 在 ! 报错信息的正下方，通常会显示类似 l.45 的标记，这代表错误发生在该 .tex 源码的 第 45 行．
  3. 观察代码截断位置：l.45 之后打印出来的代码片段中，断行或空格停顿的地方，通常就是编译器「读不下去」的具体命令所在．

物理写作十大高频报错急救方案

1.! Undefined control sequence（未定义的控制命令）

  • 产生原因：
    1. 命令名称拼写错误（例如将 \varepsilon 误打为 \varpslon）；
    2. 使用了某个宏包特有的命令，但忘记在导言区载入该宏包（例如使用了矢量加粗命令 \bm 却漏写了 \usepackage{bm}；使用了单位命令 \qty 却漏写了 \usepackage{siunitx}）．
  • 解决方案： 检查报错提示行中刚刚读取的那个反斜杠命令，确认拼写是否正确，并在导言区补齐缺失的 \usepackage{...}．

2.! Missing $ inserted 或 ! Display math should end with $$

  • 产生原因：
    1. 在正文普通文本段落中，误用了只能在数学公式环境中使用的特殊字符（最典型的是下划线 _ 和上标符 ^，例如在文件名或变量名中直接敲了 data_1.csv）；
    2. 公式环境中缺失了收尾配对的 $ 或 \]；
    3. 在行内公式 $ ... $ 内部误插入了空行（LaTeX 规定行内公式禁止分段跨行）．
  • 解决方案：
    • 纯文本中的下划线必须加反斜杠转义：写作 data\_1.csv；
    • 检查报错行附近的数学环境是否首尾严格闭合；
    • 删除公式内部不小心敲出来的空行．

3.! LaTeX Error: File 'xxx.sty' not found（找不到宏包文件）

  • 产生原因：本地 TeX 发行版中没有安装名为 xxx 的宏包（例如缺少 siunitx.sty 或 tcolorbox.sty）．
  • 解决方案：
    • 打开终端（PowerShell 或 CMD），运行 TeX Live 包管理器命令进行在线安装： 
      1
      tlmgr install xxx
    • 为了彻底根绝此类问题，建议在初次安装时直接选用 Scheme-full 完整版方案．

4. 中文字体报错：! Package fontspec Error: The font "..." cannot be found

  • 产生原因：
    1. 使用了 pdfLaTeX 引擎去编译带有 ctex 中文宏包的文档（pdfLaTeX 原生不支持调用操作系统的 TrueType/OpenType 字体）；
    2. 文档中指定了当前操作系统中不存在的专有商业字体．
  • 解决方案：
    • 将编译引擎切换为 XeLaTeX（在 VS Code 左侧 TEX 面板中选择 Recipe: XeLaTeX 即可）；
    • 中文文档类直接使用标准 \documentclass[UTF8]{ctexart}，它会自动智能匹配 Windows（中易宋体/黑体）、macOS（苹方/华文宋体）或 Linux（思源宋体）的系统预装字体，无需额外手动指定字体名称．

5. 参考文献与交叉引用显示为问号 [?] 或 (??)

  • 产生原因：编译轮次不足．LaTeX 处理交叉引用需要先在第一轮编译时将标签写入 .aux 缓存，在第二轮编译时读取并填充．对于带有 .bib 参考文献的项目，完整的解析链条是：XeLaTeX -> BibTeX -> XeLaTeX -> XeLaTeX（共需执行 4 次命令）．
  • 解决方案： 在 VS Code 中选择运行复合编译配方：XeLaTeX -> BibTeX -> XeLaTeX*2，等待整个构建流程走完即可自动恢复正常引用．

6. 辅助文件损坏导致的离奇编译死锁

  • 典型症状：代码明明完全正确，或者刚才改错了某个地方导致编译中断，修改纠正后再次编译仍然死循环报错（如报 ! File ended while scanning use of...）．
  • 产生原因：上次编译意外中断时，.aux、.toc 或 .out 辅助文件中写入了半截残缺的代码，后续每次编译加载该损坏文件都会瞬间崩溃．
  • 解决方案：
    • 在 VS Code 中点击左侧活动栏 TEX 面板 →-> Clean up auxiliary files（清理辅助文件）；
    • 或者在文件夹中手动将除 .tex、.bib 和图片之外的所有同名中间文件（.aux,.log,.out,.synctex.gz,.fls）全部删除，然后重新执行编译．

7. 浮动体图片/表格漂移到文档最末尾

  • 产生原因：在短篇幅内连续插入了多张大图，正文文字过少，超出了 LaTeX 默认单页允许容纳的浮动体数量与页面占比阈值，编译器被迫将剩余图片不断后推，直至文末集中倾倒．
  • 解决方案：
    • 在需要强行清空图片缓冲区并分页的位置加入 \clearpage 命令；
    • 或者载入 \usepackage{float}，在图表环境参数中使用大写 [H] 强制要求其就地排版．

8. 宏包加载顺序冲突（特别是 hyperref）

  • 产生原因：hyperref 宏包为了实现全文档可点击超链接，重构了底层大量标签命令．如果载入过早，会被随后载入的宏包覆盖或引起冲突．
  • 解决方案：
    • 黄金法则：原则上将 \usepackage{hyperref} 放在导言区 最后一行 载入；
    • 极少数例外宏包（如 cleveref 智能引用宏包）在官方文档中明确声明必须放在 hyperref 之后载入．

9. 编译警告：Overfull \hbox (xx pt too wide)

  • 产生原因：某一行文字、网址或超长物理公式超出了版心右边界，溢出到了页面右侧边缘．
  • 解决方案：
    • 对于长公式，使用 align、split 或 multline 手动寻找物理意义明确的位置折行；
    • 对于超长网址，使用 \url{...} 命令使其支持在斜杠处自动断行．

10.siunitx 表格报错：Invalid number '...'

  • 产生原因：在使用 siunitx 的 S 列对齐小数点的表格中，表头或文字说明被误当成了数字进行解析．
  • 解决方案： 表格中的所有非数字表头文字，必须用一对花括号包裹起来进行保护，例如 {测量序号}、{波长 / \unit{\nano\meter}}．

物理排版红黑榜（Anti-patterns vs Best Practices）

糟糕写法与反模式（严禁）推荐的最佳实践（提倡）核心改进原因
直接截图手写公式或教材贴图使用标准 LaTeX 公式源码编写矢量渲染、清晰度无限、支持检索复制
用一连串连续空格 \quad\quad 强行对齐推导使用 \begin{align} ... \end{align} 并用 & 对齐自动计算间距、排版美观、支持公式单步编号
手动敲击公式单位 $v = 9.8 m/s^2$使用 siunitx 命令 \qty{9.8}{\meter\per\second\squared}保证单位正体、负指数规范排版、数字与单位间距严谨
常数底写成斜体 $e^{ix}$正体书写 $\mathrm{e}^{\mathrm{i}x}$严格区分物理变量与数学常数算子
下标一律使用斜体 $E_k, v_{max}$区分变量与文字说明 $E_{\mathrm{k}}, v_{\mathrm{max}}$符合国家标准与 IUPAP 国际物理学会规定
使用 \mathbf{\omega} 对希腊字母加粗使用 \usepackage{bm} 并使用 \bm{\omega}\mathbf 对希腊字母无效，\bm 全字符完美倾斜加粗
绘制普通全边框网格表格使用 \usepackage{booktabs} 绘制规范三线表消除繁杂纵向网格干扰，凸显物理数据行次逻辑
正文中随手写「见上图」「如前公式所示」使用 \label{...} 与 \ref{...}/\eqref{...}章节调整或增删内容时，所有编号自动化更新
手写参考文献列表 [1] 张三...采用 .bib 文件数据库配合 BibTeX/Zotero自动生成标准化引用样式，文献增减永不乱序
把几十页论文全部塞在一个 main.tex 中采用 \input{...} 分小节分模块管理工程降低文件体积、方便版本追踪、协同开发零冲突
本页面最近更新：2026/9/24 10:41:58，更新历史
发现错误？想一起完善？ 在 GitHub 上编辑此页！
本页面贡献者：Leafuke, Physics Learning Wiki Team
本页面的全部内容在 CC BY-SA 4.0 和 SATA 协议之条款下提供，附加条款亦可能应用

评论