如何在VSCode安装后配置 LaTeX 论文撰写与编译环境

VSCode 本身并不编译 LaTeX，它只是调用你系统里装好的 xelatex 或 latexmk。环境没通，插件装得再全也白搭——95% 的“点编译没反应”“PDF 出不来”“中文变方框”，都卡在同一个地方：编译器没装、PATH 没配对，或者主文件没声明。这三件事，任何一件没到位，整个编译链就断在起点，后面所有配置都成了摆设。

确认 xelatex 和 latexmk 能在终端直接运行

别信 VSCode 内置终端（Ctrl+`），它可能继承了错误的 PATH。必须用系统原生命令行验证：

• Windows：打开 cmd 或 PowerShell，运行 where xelatex 和 where latexmk，两个都得输出路径。
• macOS/Linux：打开 Terminal，运行 which xelatex 和 which latexmk，不能返回空。
• 若任一命令报 command not found，说明 TeX 发行版没装全，或 PATH 没加对——此时改 VSCode 设置毫无意义。
• Windows 安装 TeX Live 时如果漏选了“Add TeX Live to PATH”，需要手动把类似 C:\texlive\2026\bin\win32 加进系统环境变量；加完之后必须完全退出 VSCode 再重开。
• macOS 用 brew install --cask mactex 后，检查 echo $PATH 是否包含 /Library/TeX/texbin；没有就得补上。

在 settings.json 中显式定义 xelatex 工具和 recipe

LaTeX Workshop 默认用 pdflatex，中文文档一跑就挂——不是插件问题，是引擎根本不对。必须手动覆盖：

• latex-workshop.latex.tools 里定义 xelatex 工具，args 至少包含：-synctex=1（否则 PDF 点击跳不回源码）、-interaction=nonstopmode（避免卡死）、-file-line-error（精确定位报错行）、%DOCFILE%（比 %DOC% 更稳，尤其多级子目录）。
• latex-workshop.latex.recipes 中定义一个只含 xelatex 的 recipe，名字随意（如 "XeLaTeX"），但别叫 pdflatex。
• latex-workshop.latex.recipe.default 设为该 recipe 名，例如 "XeLaTeX"。
• 如果项目含参考文献，建议额外加一个 latexmk recipe，args 加上 -xelatex 和 -pdf，让 latexmk 自动决定是否跑 bibtex。

documentclass 必须用 ctexart 或 ctexrep，且首行带 [UTF8]

光装 ctex 宏包没用；xelatex 找不到系统字体就会 fallback 成方块，甚至死循环编译：

• 主 .tex 文件第一行必须是 \documentclass[UTF8]{ctexart}（论文用）或 {ctexrep}（报告用），不能是 article + 手动加 xeCJK。
• 导言区显式声明中文字体：\setmainfont{Noto Serif CJK SC}（macOS/Linux），或 \setmainfont{"Microsoft YaHei"}（Windows，带空格必须加引号）。
• 主文件顶部加注释：% !TEX root = main.tex（哪怕就一个文件，也得写）；否则插件不认它是入口，\cite{}、\ref{} 全失效。
• 别重复加载 fontspec 或 xeCJK——ctex 已内置，冲突会导致字体加载失败。

PDF 预览失效？重点查 -synctex=1、输出路径和 viewer 配置

VS Code 内置 PDF 查看器依赖 synctex 信息，而这个信息必须由编译器生成，且路径不能被拦截：

• 确认编译命令含 -synctex=1 参数（上面 xelatex 示例已包含）。
• PDF 输出路径不能跨盘符或含空格/中文——比如 D:\My Papers\thesis.pdf 可能触发安全限制，建议用默认 ./out/ 目录。
• 如果用外部阅读器（如 SumatraPDF），需额外配置 latex-workshop.view.pdf.external.viewer.command，且必须关闭其「只允许一个实例」选项，否则反向同步（Ctrl+Click 跳回源码）会失败。

最常被忽略的是：改完 PATH 后没重启 VSCode，或主文件没加 % !TEX root 注释——这两处一错，整个编译链就断在起点，后面所有配置都无效。