怎么用VSCode编写LaTeX论文-环境搭建与实时编译指南

怎么用VSCode编写LaTeX论文-环境搭建与实时编译指南

很多朋友上手VSCode写LaTeX，容易陷入一个误区：以为编译是编辑器完成的。其实不然，VSCode本身只是个调度员，真正负责把.tex文件变成PDF的，是你系统里安装的xelatex、latexmk这些工具链。环境没配好，插件装再多也是徒劳。

确认本地 TeX 工具链是否就位

几乎所有编译问题的根源，都出在这一步。如果VSCode报"xelatex not found"这类错误，十有八九是工具链没接通。

• 首先，打开你系统的终端（先别用VSCode内置的），分别运行xelatex --version和latexmk --version。两个命令都必须能正常输出版本号，这才算过关。
• Windows用户注意：安装TeX Live时，务必勾选“Add TeX Live to PATH”。如果当时漏了，需要手动将类似C:\texlive\2024\bin\win32的路径添加到系统环境变量中。
• macOS用户注意：推荐用brew install --cask mactex安装完整套件。别用basictex，它默认不包含latexmk。安装后，在终端执行echo $PATH，确认/Library/TeX/texbin这个路径已经包含在内。
• Linux用户注意：执行sudo apt install texlive-latex-recommended texlive-latex-extra latexmk。只安装texlive-base是远远不够的。
• 完成上述任何一步路径修改后，必须完全重启VSCode（不是仅仅重载窗口），编辑器才能读取到新的系统PATH。

LaTeX Workshop 编译配置必须显式指定 xelatex

插件默认的编译方案用的是pdflatex，用它处理中文文档，结果不是乱码就是报字体缺失——这可不是插件有问题，纯粹是引擎选错了。

• 在VSCode设置中搜索latex-workshop.latex.recipes，点击“在settings.json中编辑”，填入以下配置：

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

• 这里有个关键细节：使用%DOCFILE%（当前文件名含路径）比%DOC%更可靠，尤其是在主文档和子文件不在同一目录的复杂项目中。
• -synctex=1这个参数必须加上，否则生成的PDF将无法实现点击跳转回源码位置的反向搜索功能。
• 最后提醒一句：别同时启用多个LaTeX插件（比如LaTeX Tools），它们之间很容易产生冲突，导致行为异常。

中文支持失效的三个硬性条件

以为装了ctex宏包就万事大吉？没那么简单。如果xelatex找不到系统字体，它要么用方块字敷衍你，要么直接陷入死循环。

• 字体必须显式声明：在文档导言区，务必写明中文字体。例如，macOS/Linux可以用\setmainfont{Noto Serif CJK SC}，Windows则用\setmainfont{"Microsoft YaHei"}（注意，字体名含空格时必须加引号）。
• 主文档必须被识别：在主.tex文件的第一行，加上注释% !TEX root = main.tex。否则，插件可能无法识别它是需要编译的入口文件。
• 路径必须“干净”：如果你的项目放在iCloud、OneDrive这类同步盘，或者路径中包含中文、空格，latexmk很可能会直接报错Filename contains character not allowed for TeX file。最稳妥的办法，是把项目移到纯英文、无空格的路径下（比如~/latex-paper）再试。

PDF 不刷新、参考文献不更新、预览空白

遇到这些问题先别慌，它们往往不是编译失败了，而是完整的构建流程没跑完，或者文件监听没生效。

• 参考文献需要多次编译：首次编译带参考文献的文档时，别依赖“保存即编译”功能。手动按Ctrl+Alt+B（Windows）或Cmd+Alt+B（Mac），至少完整执行两到三遍xelatex → bibtex → xelatex的流程。
• 考虑换用外部PDF查看器：VSCode内置的PDF查看器有时会卡死或不同步。可以在设置里，将latex-workshop.view.pdf.viewer从tab模式改为external，关联到SumatraPDF（Windows）或Skim（Mac）这类专业工具。
• 检查.bib文件路径：\bibliography{refs}这条命令，默认寻找的是refs.bib文件。如果你的文献数据库放在子目录里，比如./bib/refs.bib，那么命令必须写成\bibliography{bib/refs}。
• 理解自动构建的局限：确认latex-workshop.latex.autoBuild.run是否设为onFileChange。但要知道，这个监听通常不覆盖.bib文件或子目录下的.tex文件变动。

最后分享一个最容易被忽略的“坑”：VSCode集成终端的PATH环境变量，可能和你系统终端的PATH不一样。而插件调用命令时，用的是集成终端的环境。这就解释了为什么在iTerm或CMD里能跑通的xelatex，在VSCode里却报错。最快的验证方法就是：打开VSCode的内置终端，亲手把编译命令敲一遍试试。