VS Code 配置 LaTeX 完整教程：从 TeXstudio 迁移到 LaTeX Workshop
VS Code 配置 LaTeX 完整教程：从 TeXstudio 迁移到 LaTeX Workshop
之前使用 TeXstudio 编译正常，但切换到 VS Code 后出现参考文献、章节、图表编号无法显示，主要原因是：
- VS Code 需要额外安装 LaTeX 编译扩展；
- 工程路径中的中文字符可能导致编译器乱码；
- 参考文献需要执行 BibTeX；
- 章节、图表和公式编号需要多轮编译；
- VS Code 的普通“运行”按钮不是 LaTeX 编译按钮。
本文以 Windows、TeX Live 和 VS Code 为例，介绍完整配置方法。
一、LaTeX 编译环境的组成
LaTeX 项目通常包含三部分：
VS Code ↓ LaTeX Workshop 扩展 ↓ TeX Live / MiKTeX 编译环境其中：
- VS Code：编辑器；
- LaTeX Workshop：负责调用编译命令；
- TeX Live 或 MiKTeX：真正执行 XeLaTeX、BibTeX 等编译程序。
TeXstudio 本身也是编辑器，之前能够正常编译，说明电脑中大概率已经安装了 TeX Live 或 MiKTeX。
终端检查VS Code、LaTeX Workshop、TeX Live版本信息
建议在终端检查：
xelatex--version bibtex--version latexmk--version如果能够显示版本号，说明编译环境已经安装。
LaTeX Workshop 官方安装说明：
LaTeX Workshop Installation
二、安装 VS Code 扩展
在 VS Code 左侧打开扩展商店，搜索并安装：
LaTeX Workshop也可以按：
Ctrl + P输入：
ext install latex-workshopLaTeX Workshop 可以提供：
- 编译
.tex文件； - 自动调用 BibTeX；
- 生成 PDF；
- PDF 与源码正反向跳转；
- 公式、章节和引用补全；
- 编译错误和警告提示。
图1：VS Code 扩展商店中的 LaTeX Workshop
三、工程路径尽量使用英文
Windows 下，较旧版本的 TeX Live、Perl 和 latexmk 可能无法正确处理中文路径。
不推荐：
D:\中文文件\中文路径\论文排版2026\建议使用：
D:\LaTeX\Paper_path\project_path工程目录可以包含：
project_path/ ├── paper.tex ├── refs.bib ├── figs/ └── .vscode/ └── settings.json然后在 VS Code 中选择：
文件 → 打开文件夹打开整个工程目录，而不是只打开某个.tex文件。
图2：VS Code 中打开完整 LaTeX 工程目录
四、配置settings.json
在工程目录下创建：
.vscode/settings.json写入以下内容：
{"latex-workshop.latex.tools":[{"name":"xelatex","command":"xelatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"bibtex","command":"bibtex","args":["%DOCFILE%"]}],"latex-workshop.latex.recipes":[{"name":"XeLaTeX -> BibTeX -> XeLaTeX x2","tools":["xelatex","bibtex","xelatex","xelatex"]}],"latex-workshop.latex.recipe.default":"XeLaTeX -> BibTeX -> XeLaTeX x2","latex-workshop.view.pdf.viewer":"tab"}其中：
%DOC%表示当前主.tex文件的完整路径。
%DOCFILE%表示不带扩展名的主文件名，例如：
paper五、为什么需要四步编译
参考文献、章节、图、表和公式编号不能通过一次编译完成。
完整流程为：
第一次 XeLaTeX ↓ 生成 .aux 文件 ↓ BibTeX 读取 refs.bib ↓ 生成 .bbl 文件 ↓ 第二次 XeLaTeX ↓ 加载参考文献和交叉引用 ↓ 第三次 XeLaTeX ↓ 确定最终编号因此配置中的：
"tools":["xelatex","bibtex","xelatex","xelatex"]不能删除或重复。
六、正确的编译方式
不要使用 VS Code 右上角普通的三角形“运行”按钮。
应使用以下方法之一。
方法一：快捷键
Ctrl + Alt + B方法二：命令面板
按：
Ctrl + Shift + P输入：
LaTeX Workshop: Build with recipe选择：
XeLaTeX -> BibTeX -> XeLaTeX x2方法三：左侧 TeX 面板
点击左侧的 TeX 图标，然后点击：
Build LaTeX project图3：LaTeX Workshop 的 Build with recipe 菜单
七、如何查看编译日志
编译后按：
Ctrl + J打开底部面板，点击：
OUTPUT在右侧下拉框中选择：
LaTeX Compiler正常日志应该包含：
Running 'xelatex ...' Running 'bibtex paper' Running 'xelatex ...' Running 'xelatex ...'最后应看到：
Output written on paper.pdf以及：
Transcript written on paper.log八、参考文献的正确配置
主文件末尾使用 BibTeX 时，应写成：
\bibliographystyle{cas-model2-names} \bibliography{refs}注意不要写成：
\bibliography{refs.bib}正文引用示例：
Recent studies have explored lightweight networks \citep{wang2024yolov9}.参考文献文件应位于：
refs.bib并且和主文件位于同一个工程目录中。
九、常见 BibTeX 错误
1. 重复引用键
错误：
Repeated entry---line ...说明多个条目使用了相同的键，例如：
@article{liu2024edge,同一个引用键只能出现一次。
2. 不支持的条目类型
错误：
entry type for "yolov8_ultralytics" isn't style-file defined例如：
@software{yolov8_ultralytics,可以改为：
@misc{yolov8_ultralytics, author = {Jocher, Glenn and Chaurasia, Ayush and Qiu, Jing}, title = {Ultralytics YOLOv8}, year = {2023}, howpublished = {\url{https://github.com/ultralytics/ultralytics}} }3.@inproceedings缺少booktitle
错误：
empty booktitle in wang2024yolov10如果条目类型是：
@inproceedings应使用：
booktitle = {Advances in Neural Information Processing Systems},而不是：
journal = {Advances in Neural Information Processing Systems},4. 清理后直接运行 BibTeX
如果出现：
I couldn't open file name `COMPAG_LED-Inst.aux'说明还没有先运行 XeLaTeX。
正确顺序是：
XeLaTeX → BibTeX → XeLaTeX → XeLaTeX不能清理辅助文件后直接运行 BibTeX。
十、章节、图表和公式引用
推荐使用不含空格的标签：
\section{Related Work} \label{sec:related-work}正文引用：
Section~\ref{sec:related-work}图片：
\caption{Overall architecture of the proposed framework.} \label{fig:framework}正文引用：
Fig.~\ref{fig:framework}表格：
\caption{Experimental results.} \label{tab:results}正文引用：
Table~\ref{tab:results}\label的推荐位置：
\caption{...} \label{fig:example}也就是放在\caption后面。
十一、如何清理并重新编译
如果 PDF 中仍然出现：
??或者：
[?]可以清理辅助文件。
按：
Ctrl + Shift + P执行：
LaTeX Workshop: Clean up auxiliary files然后重新执行：
LaTeX Workshop: Build with recipe选择：
XeLaTeX -> BibTeX -> XeLaTeX x2最后按：
Ctrl + Alt + V重新打开 PDF。
十二、日志中的警告如何判断
以下警告通常不影响 PDF 生成：
Underfull \hbox Overfull \hbox它们表示排版时某些行太松或太宽。
以下警告说明交叉引用还没有完成：
Reference ... undefined Citation ... undefined第一次 XeLaTeX 编译时出现这些警告是正常的，只要最终一次编译中不再出现即可。
真正需要优先处理的是：
There were ... error messages或者：
Fatal error总结
从 TeXstudio 迁移到 VS Code，最重要的是掌握下面这条逻辑：
安装 TeX Live 或 MiKTeX ↓ 安装 LaTeX Workshop ↓ 打开完整工程文件夹 ↓ 配置 .vscode/settings.json ↓ 使用 XeLaTeX -> BibTeX -> XeLaTeX x2 ↓ 查看 LaTeX Compiler 日志 ↓ 重新打开生成的 PDF只要工程路径正常、refs.bib语法正确，并且使用完整的四步编译流程，参考文献、章节、图表和公式编号就可以在 VS Code 中正常生成。