如何在VSCode中编写LaTeX文档并编译？【教程】

需安装TeX发行版（windows用TeX Live、macOS用MacTeX、linux用texlive-full/most）和vscode的LaTeX Workshop扩展；配置xelatex为默认引擎，设置ctex宏包与中文字体，用biblatex+biber管理参考文献，并按xelatex→biber→xelatex→xelatex顺序编译。

安装 LaTeX 工具链和 VSCode 扩展

VSCode 本身不带 LaTeX 编译能力，必须手动配置底层工具链和编辑器支持。Windows 用户推荐安装 TeX Live（完整版），macOS 用户用 MacTeX，Linux 用户可选 texlive-full（ubuntu/debian）或 texlive-most（Arch）。装完后终端运行 pdflatex --version 或 xelatex --version 能输出版本号才算成功。

VSCode 扩展只装一个：官方维护的 LaTeX Workshop。不要同时启用其他 LaTeX 插件（如 LaTeX Tools），它们会冲突。安装后重启 VSCode，插件会自动检测本地 TeX 发行版路径——若未识别，需手动在 settings.json 中设置："latex-workshop.latex.tools" 和 "latex-workshop.latex.recipes"。

配置编译命令与默认引擎

LaTeX Workshop 默认使用 pdflatex，但中文、字体或特殊符号常需 xelatex 或 lualatex。直接改默认 recipe 更可靠：

{   "latex-workshop.latex.recipes": [     {       "name": "xelatex",       "tools": ["xelatex"]     }   ],   "latex-workshop.latex.tools": [     {       "name": "xelatex",       "command": "xelatex",       "args": [         "-synctex=1",         "-interaction=nonstopmode",         "-file-line-error",         "%DOC%"       ]     }   ] }

关键点：%DOC% 是占位符，代表当前打开的主 .tex 文件；-synctex=1 启用正向/反向同步；-interaction=nonstopmode 避免编译卡在错误提示上。

处理中文、字体和参考文献

中文支持不能只靠 ctex 宏包，还依赖引擎和字体配置。用 xelatex 时，导言区必须包含：

usepackage{ctex} setmainfont{Noto Serif CJK SC} % 或系统已安装的中文字体，如 "SimSun"、"PingFang SC" setsansfont{Noto Sans CJK SC} setmonofont{Noto Sans Mono CJK SC}

参考文献推荐 biblatex + biber 组合（比传统 bibtex 更兼容 Unicode）：

• 导言区加 usepackage[backend=biber]{biblatex} 和 addbibresource{references.bib}
• 在 settings.json 中为 biber 单独配 tool："name": "biber", "command": "biber", "args": ["%DOCFILE%"]
• recipe 中按顺序调用：xelatex → biber → xelatex → xelatex（两次编译确保交叉引用正确）

常见编译失败原因与排查

报错信息往往藏在 VSCode 右下角状态栏或 LaTeX Compiler 输出面板里。高频问题包括：

• File not found: xxx.aux：首次编译前删掉所有辅助文件（.aux、.log、.out 等），或用 LaTeX Workshop 提供的 Clean auxiliary files 命令
• undefined control sequence：检查宏包是否漏加载（如用 textcircled 却没加 amsmath），或命令拼写错误（ref 写成 reft）
• PDF 不更新：确认当前打开的是主文件（含 documentclass），且右键菜单中 Set as root document 已激活；子文件需用 input{xxx} 或 include{xxx} 引入
• 中文乱码或方块字：确认用了 xelatex 而非 pdflatex，且 setmainfont 指定的字体名与系统实际安装名称完全一致（大小写、空格、中英文括号都算）

最易被忽略的是工作区设置覆盖用户设置——如果项目根目录有 .vscode/settings.json，它会优先生效，务必检查其中是否误删了 latex-workshop 相关配置。