VSCode LaTeX配置_学术论文写作与实时编译环境-VSCode-PHP中文网

vscode运行latex需配置系统工具链与主文档声明：安装tex发行版并加入path，主文件首行加% !tex root；中文用xelatex+ctex+显式字体；参考文献需正确路径及bibtex/biber配合编译。

vscode latex配置_学术论文写作与实时编译环境

VSCode 能跑 LaTeX 论文，但不是装个插件就完事——它根本不会自己找 latexmk、xelatex 或 bibtex，所有编译失败，90% 都卡在系统 PATH 没通或主文档没声明。

这是最常卡住的第一步。LaTeX Workshop 默认调用 latexmk，但它必须已安装且能被 VSCode 终端识别。

macOS：运行 brew install --cask mactex（别用 basictex，它默认不含 latexmk）；装完重启终端和 VSCode，再在集成终端里执行 which latexmk，有输出才算成功
Windows：从 tug.org/texlive 下载完整版安装器，安装时务必勾选 “Add TeX Live to PATH”；若已装过却没勾，手动把类似 C:\texlive\2024\bin\win32 的路径加进系统环境变量
Linux（Ubuntu/Debian）：运行 sudo apt install texlive-latex-recommended texlive-latex-extra latexmk，别只装 texlive-base
验证方式：在 VSCode 集成终端中直接运行 latexmk -v，输出版本号才算真正就位；如果报错，按 Ctrl+Shift+P → 输入 Developer: Toggle Developer Tools，看 Console 里有没有 spawn latexmk ENOENT，有就是 PATH 问题

用 xelatex 是对的，但光换引擎不够，缺字体配置等于白搭——xelatex 不会自动猜你系统里装了什么中文字体。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

macOS：导言区加 \usepackage{ctex} 和 \setmainfont{Noto Serif CJK SC}（推荐，免版权风险）；别依赖 ctex 默认字体，它在某些 macOS 版本下 fallback 到空字形
Windows：用 \setmainfont{"Microsoft YaHei"} 或 \setmainfont{SimSun}，注意带空格的字体名必须用英文双引号包裹，否则编译静默失败
必须确认 VSCode 状态栏右下角显示的是 XeLaTeX，不是 PdfLaTeX；右键编辑器空白处 → “LaTeX Workshop: Set Compiler to XeLaTeX”，这个操作要手动做一次，不会自动识别
如果仍报错“font-not-found”，在终端运行 fc-list :lang=zh（macOS/Linux）或 Get-FontFile | Where-Object {$_.Culture -eq 'zh-CN'}（PowerShell），确认字体确实注册到了系统级字体库

不是插件坏了，是 SyncTeX 参数或主文档标识没生效——LaTeX Workshop 只对明确标记为“主”的文件启用同步和监听。

在主 .tex 文件第一行或前几行加上注释：% !TEX root = main.tex（哪怕就是当前文件，也得写）；不加这句，\input{chapter1} 或 \bibliography{refs} 全部被忽略
检查 latex-workshop.latex.tools 设置里，对应引擎（如 xelatex）的 args 是否含 -synctex=1；若用 latexmk，也要确保其 args 包含该参数，否则 .synctex.gz 根本不生成
VSCode 内置 PDF 查看器（tab 模式）在长文档中容易卡死或不同步；建议改用外部查看器：latex-workshop.view.pdf.viewer 设为 external，macOS 配 Skim，Windows 配 SumatraPDF
首次编译建议手动按 Ctrl+Alt+B（Win/Linux）或 Cmd+Alt+B（macOS），别依赖保存即编译——尤其带参考文献的文档，latexmk 需要多遍才能把 .bib 数据刷进 PDF

不是 .bib 文件写错了，而是编译流程没跑全，或者路径没被 LaTeX Workshop 解析到。

\bibliography{refs} 中的 refs 指的是 refs.bib，但该文件必须和主 .tex 在同一目录，或用相对路径写全，比如 \bibliography{./refs}
如果用了 latexmk，它的默认行为不一定触发 BibTeX；需在 latex-workshop.latex.tools 的 latexmk 条目 args 中显式加 -bibtex 和 -f（强制重跑）
如果坚持用 xelatex → bibtex → xelatex ×2 手动流程，要在 latex-workshop.latex.recipes 中定义完整 recipe，并设为 default；否则按快捷键只会跑一遍 xelatex
编译后检查项目目录下是否生成了 main.bbl；没有，说明 BibTeX 根本没执行；有但内容为空，说明 .bib 路径或条目格式（如缺失 author 或 year）有问题