一、Overleaf报错的基本排查方法
在逐一讲解错误之前,先掌握通用排查技巧:
查看报错信息的方法:
Overleaf界面 → 点击红色错误图标(或"Logs and output files")
→ 查看错误列表 → 点击具体错误跳转到对应行
排查三步法:
- 看报错信息中的行号 -- 定位出错位置
- 看报错信息中的关键词 -- 判断错误类型
- 检查该行及上下文 -- 通常错误在报错行或其前一行
重要认知: LaTeX报错的行号不一定精确指向真正出错位置,实际错误可能在报错行之前的几行。

二、语法错误类(6个)
错误1:Undefined control sequence
! Undefined control sequence.
l.45 \begn{equation}
| 原因 |
修复 |
| 命令拼写错误 |
\begn → \begin;\inclucegraphics → \includegraphics |
| 使用了未导入宏包的命令 |
添加对应的\usepackage{xxx} |
| 自定义命令未定义 |
确认` |
| ewcommand`在使用之前 |
|
最常见拼写错误:
| 错误写法 |
正确写法 |
\textbf{ 少了右括号 |
\textbf{text} |
\usepackge |
\usepackage |
\bgin{figure} |
\begin{figure} |
\labei |
\label |
错误2:Missing $ inserted
! Missing $ inserted.
l.52 The value of x_1 is...
| 原因 |
修复 |
正文中使用了数学符号(_、^、\sum等)未用$包裹 |
x_1 → $x_1$ |
| 命令中意外出现下划线 |
文件名中的_改为\_或放入\texttt{} |
常见触发场景:
% 错误:正文中直接写下划线/上标
The value of x_1 is greater than x_2.
% 正确:数学符号用$包裹
The value of $x_1$ is greater than $x_2$.
% 错误:文件名含下划线未转义
\includegraphics{my_figure_v2.pdf}
% 正确(多数情况下路径中的下划线其实没问题,
% 但如果报错可以尝试):
\includegraphics{my\_figure\_v2.pdf}
错误3:Environment ended by wrong command
! LaTeX Error: \begin{figure} on input line 30 ended by \end{table}.
| 原因 |
修复 |
\begin和\end不匹配 |
检查环境嵌套是否正确闭合 |
遗漏了某个\end{...} |
逐层检查嵌套结构 |
快速定位法: 搜索报错行附近的所有\begin和\end,确认配对关系。
错误4:Too many }'s / Extra }
| 原因 |
修复 |
多写了一个右花括号} |
检查该行附近括号配对 |
少写了一个左花括号{ |
向前查找未闭合的命令 |
技巧: 在Overleaf中点击任何括号,对应的匹配括号会高亮显示。
错误5:Missing \begin{document}
! LaTeX Error: Missing \begin{document}.
| 原因 |
修复 |
| 导言区有非法字符/文字 |
所有正文内容必须在\begin{document}之后 |
\begin{document}拼写错误 |
检查拼写 |
| 导言区宏包有报错导致文档无法开始 |
先修复导言区的其他错误 |
| 文件编码问题(BOM头) |
在Overleaf中新建文件重新粘贴内容 |
错误6:Runaway argument / Paragraph ended before command
Runaway argument?
! Paragraph ended before \xxx was complete.
| 原因 |
修复 |
| 某个命令的花括号未闭合 |
向前查找缺少}的命令 |
| 命令参数中意外出现空行 |
删除参数内的空行 |
% 错误:\textbf内有空行
\textbf{This is bold
text} % 空行导致错误
% 正确
\textbf{This is bold text}
三、浮动体与图表错误类(5个)
错误7:File 'xxx.png' not found
! LaTeX Error: File `figures/model.png' not found.
| 原因 |
修复 |
| 文件路径错误 |
确认文件确实在指定路径 |
| 文件名大小写不匹配 |
Linux区分大小写:Model.png ≠ model.png |
| 文件未上传到Overleaf |
上传图片文件到项目中 |
| 后缀名写错 |
.png vs .jpg vs .pdf |
建议: 在Overleaf左侧文件栏确认图片文件存在且路径正确。
错误8:Unknown graphics extension
! LaTeX Error: Unknown graphics extension: .tif
| 原因 |
修复 |
| pdflatex不支持该图片格式 |
将.tif/.bmp转换为.pdf/.png/.jpg |
| eps文件未正确处理 |
添加\usepackage{epstopdf}或转为PDF |
pdflatex支持的图片格式: PDF、PNG、JPG、JPEG
错误9:Float too large / Float specifier changed
! LaTeX Error: Float(s) lost.
或
LaTeX Warning: `h' float specifier changed to `ht'.
| 原因 |
修复 |
| 图/表过大无法放入页面 |
缩小图片width=0.9\columnwidth |
| 过多浮动体堆积 |
添加\clearpage强制输出 |
[h]位置不可用被改为[ht] |
使用[htbp]给LaTeX更多选择 |
推荐浮动体位置参数:
\begin{figure}[t] % 优先顶部(学术论文最常用)
\begin{figure}[htbp] % 给LaTeX最大自由度
错误10:Overfull \hbox(图片/表格超宽)
Overfull \hbox (15.2pt too wide) in paragraph at lines 89--95
| 原因 |
修复 |
| 图片宽度超出栏宽 |
减小width参数 |
| 表格列宽总和超出 |
缩小字号或减少列 |
| 长URL/长单词无法断行 |
使用\url{}或\sloppy |
% 图片修复
\includegraphics[width=\columnwidth]{fig.pdf} % 不超过栏宽
% 表格修复:缩小字号
{\small
\begin{tabular}{...}
...
\end{tabular}
}
% 长词断行修复
\usepackage[hyphens]{url}
错误11:Not in outer par mode(浮动体嵌套)
! LaTeX Error: Not in outer par mode.
| 原因 |
修复 |
| figure/table嵌套在另一个figure/table内 |
浮动体不能嵌套 |
| 在minipage等盒子内使用浮动体 |
改用非浮动方式放置 |
四、参考文献错误类(4个)
错误12:Citation 'xxx' undefined
LaTeX Warning: Citation `zhang2024method' undefined.
| 原因 |
修复 |
| .bib文件中没有该key |
检查.bib中key拼写 |
| .bib文件未正确链接 |
确认\bibliography{filename}中文件名正确(不加.bib后缀) |
| 需要重新编译 |
Overleaf中点击Recompile(有时需要两次) |
| key中有特殊字符 |
避免在cite key中使用空格/特殊字符 |
错误13:I found no \citation commands / Empty bibliography
I found no \citation commands---while reading file paper.aux
| 原因 |
修复 |
正文中没有任何\cite{}命令 |
添加引用 |
\bibliography路径错误 |
确认.bib文件存在且名称正确 |
\bibliographystyle缺失 |
添加\bibliographystyle{IEEEtran} |
错误14:BibTeX错误 - illegal end of database file
I was expecting a `,' or a `}'---line 45 of file refs.bib
| 原因 |
修复 |
| .bib条目语法错误 |
检查括号/逗号/引号配对 |
| 条目缺少必要字段 |
补充author/title/year等字段 |
| 特殊字符未转义 |
& → \&;% → \% |
常见.bib语法错误:
% 错误:最后一个字段后多了逗号
@article{key,
author = {Zhang},
title = {Title},
year = {2024}, ← 最后一个字段后的逗号(部分情况会报错)
}
% 错误:字段值中有未转义的特殊字符
title = {Method for A & B} ← & 需要转义为 \&
错误15:Repeated entry
Warning--I didn't find a database entry for "Zhang2024"
| 原因 |
修复 |
\cite{}中的key与.bib中不匹配 |
大小写敏感,检查完全一致 |
| 多个.bib文件中有重复key |
重命名或删除重复条目 |
五、格式与排版错误类(5个)
错误16:Overfull \hbox(正文文字溢出)
Overfull \hbox (3.5pt too wide) in paragraph at lines 120--125
| 原因 |
修复 |
| 长单词/术语无法断行 |
添加\hyphenation{}或使用\sloppy |
| URL过长 |
使用\url{}宏包(自动断行) |
| 轻微溢出(1-3pt) |
可忽略或微调措辞 |
全局宽松断行(牺牲少许美观性):
\sloppy % 在导言区添加,允许更宽松的断行
错误17:Underfull \hbox / \vbox
Underfull \hbox (badness 10000) in paragraph at lines 88--92
| 原因 |
修复 |
| 段落断行后某行文字太少 |
微调措辞使文字更均匀分布 |
强制换行\\使用不当 |
正文中用空行换段而非\\ |
| 页面底部留白过多 |
通常可忽略(Warning非Error) |
注意: Underfull通常是Warning而非Error,不影响编译成功,但过多的Underfull说明排版不够紧凑。
错误18:Package hyperref Warning: Token not allowed
Package hyperref Warning: Token not allowed in a PDF string
| 原因 |
修复 |
| 标题/书签中使用了数学命令 |
在section标题中用\texorpdfstring |
| PDF元数据中有不兼容命令 |
简化hyperref设置 |
% 错误:section标题含数学命令
\section{Analysis of $O(n\log n)$ Algorithm}
% 正确:使用texorpdfstring
\section{Analysis of \texorpdfstring{$O(n\log n)$}{O(n log n)} Algorithm}
错误19:Caption outside float
! LaTeX Error: \caption outside float.
| 原因 |
修复 |
\caption不在figure/table环境内 |
确认caption在正确的环境中 |
| 环境被意外关闭 |
检查\end{figure}位置 |
错误20:Package/Option clash
! LaTeX Error: Option clash for package graphicx.
| 原因 |
修复 |
| 同一宏包被加载两次且选项不同 |
删除重复的\usepackage,保留一个 |
| 模板cls已加载了该宏包 |
删除你手动添加的\usepackage |
% 错误:重复加载
\usepackage[pdftex]{graphicx}
\usepackage{graphicx} % 冲突
% 正确:只保留一个(或不带选项)
\usepackage{graphicx}
六、Overleaf特有问题
| 问题 |
原因 |
解决方法 |
| 编译超时(Timeout) |
项目过大或图片过多 |
压缩图片;拆分文件用\input{} |
| "Compile from scratch" |
缓存出问题 |
点击Logs旁的垃圾桶图标清缓存 |
| PDF不更新/显示旧版 |
浏览器缓存 |
强制刷新(Ctrl+Shift+R) |
| 中文无法显示 |
未配置中文编译器 |
切换编译器为XeLaTeX + 添加\usepackage{ctex} |
| 协作者修改后编译失败 |
冲突/语法被破坏 |
用Git历史恢复到正确版本 |
切换编译器方法:
Overleaf菜单 → Settings → Compiler →
选择 pdfLaTeX / XeLaTeX / LuaLaTeX
七、报错速查对照表
| 报错关键词 |
最可能原因 |
第一步操作 |
Undefined control sequence |
命令拼写错误 |
检查报错行的命令拼写 |
Missing $ |
数学符号在正文中 |
给_、^等加上$...$ |
File not found |
路径/文件名错误 |
确认文件存在且大小写一致 |
\begin ended by \end |
环境不匹配 |
检查begin/end配对 |
Too many }'s |
括号多余 |
检查报错行附近的括号 |
Overfull \hbox |
内容超出宽度 |
缩小图片/缩短文字/允许断行 |
Citation undefined |
引用key不存在 |
检查.bib中key拼写 |
Option clash |
宏包重复加载 |
删除重复的usepackage |
Float(s) lost |
浮动体堆积/过大 |
缩小图表或添加\clearpage |
Runaway argument |
花括号未闭合 |
向前查找缺少}的位置 |
八、总结
遇到Overleaf报错时的通用处理流程:
1. 查看错误日志 → 定位行号和关键词
2. 检查报错行及其前2-3行
3. 对照本文速查表确定错误类型
4. 按对应修复方法处理
5. 重新编译确认错误消失
6. 如有多个错误,优先修复第一个(后续错误可能是连锁反应)
三条核心经验:
- 先修第一个错误 -- LaTeX的错误具有级联效应,第一个错误可能导致后面10+个假错误
- 善用Overleaf的错误定位 -- 点击错误信息可跳转到对应行
- 编译频繁 -- 每写完一个段落/公式/图表就编译一次,错误越早发现越容易定位
LaTeX报错看起来吓人,但95%的错误都是拼写、括号、路径这三类低级问题。熟悉常见报错信息后,修复通常只需要几秒钟。