VSCode写Latex环境配置？论文排版从零开始【实战】-VSCode-PHP中文网

VSCode编译LaTeX失败90%因xelatex/latexmk未正确配置：需先在终端验证xelatex --version和latexmk --version能输出版本号，确保PATH包含TeX Live的bin路径（如macOS的/usr/local/texlive/2026/bin/universal-darwin），并重启VSCode；LaTeX Workshop仅调度系统工具，不自带编译器。

vscode写latex环境配置？论文排版从零开始【实战】

VSCode 编译 LaTeX 失败，90% 的原因是 xelatex 或 latexmk 在终端里根本跑不起来——LaTeX Workshop 只是调度器，不是编译器本身。

终端里跑不通 `xelatex --version`，VSCode 就一定编译失败

LaTeX Workshop 不自带任何编译命令，它完全依赖系统 PATH 中的可执行文件。你在 VSCode 内置终端（Ctrl+`）里输入：

xelatex --version

如果报 command not found 或 zsh: command not found: xelatex，那就别急着改 VSCode 配置，先解决路径问题。

macOS（MacTeX）：安装后默认路径是 /usr/local/texlive/2026/bin/universal-darwin，需手动加进 ~/.zshrc：
export PATH="/usr/local/texlive/2026/bin/universal-darwin:$PATH"
Windows（TeX Live）：安装时必须勾选 “Add TeX Live to PATH”，否则要手动把 C:\texlive\2026\bin\win32 加进系统环境变量
Linux（Ubuntu）：别只装 texlive-base，得装 texlive-full + latexmk：
sudo apt install texlive-full latexmk

验证方式：在 VSCode 终端中运行 which xelatex 和 which latexmk，两个都必须有输出。

`ctex` + `XeLaTeX` 是中文论文唯一靠谱组合

用 article 类自己硬塞 xeCJK，大概率会遇到字体找不到、fontspec 报错、章节编号乱码等问题。原因很简单：ctex 已经封装了编码处理、中文字体映射、标题样式、页眉页脚等一整套逻辑，XeLaTeX 则原生支持系统字体和 UTF-8。

VSCode

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

下载

主文件第一行必须是：\documentclass[UTF8]{ctexart}（或 ctexrep/ctexbook）
导言区不要再加载 fontspec、xeCJK 或 ctex 的子宏包——重复加载会触发冲突，常见报错如 ! Package fontspec Error: The font "SimSun" cannot be found.
如果要用自定义字体（比如“思源宋体”），直接在 ctexset 里设：
\ctexset{section = {name-format = \bfseries, number = \arabic{section}}}，再配合 \setmainfont{Source Han Serif SC}

多文件项目必须显式声明 `% !TEX root`

VSCode 默认只把当前打开的 .tex 文件当编译目标。如果你把正文拆成 intro.tex、method.tex、result.tex，又没指明哪个是主文件，\ref、\cite、bibtex 全都会失效，报错类似 undefined reference 或 citation undefined。

最可靠做法：在主文件（如 main.tex）顶部第一行加注释：
% !TEX root = main.tex
不要依赖插件自动探测——尤其当目录下有多个 .tex 文件时，它常把 appendix.tex 当成主文件
若用 latexmk，确保 .latexmkrc 里写了：
$pdflatex = 'xelatex -synctex=1 -interaction=nonstopmode %O %S';

PDF 预览不刷新？先关掉 tab 模式

LaTeX Workshop 默认启用 PDF 预览的 tab 模式（即嵌入 VSCode 标签页），但这个模式在 XeLaTeX 编译后经常卡住不刷新，尤其是 macOS 上。这不是配置错误，是插件已知限制。

临时解决：右键 PDF 预览区域 → “Reveal in Finder” → 用 Skim（macOS）或 SumatraPDF（Windows）这类支持反向搜索和热重载的外部查看器打开
长期设置：在 settings.json 中禁用内建预览：
"latex-workshop.view.pdf.viewer": "external"
关键参数不能少：所有 xelatex 的 args 必须含 -synctex=1（用于正反向跳转）和 -interaction=nonstopmode（避免报错中断编译）

真正容易被忽略的是：路径里有中文或空格（比如 毕业论文 v2/）、.bib 文件编码不是 UTF-8、bibtex 命令被误写成 bibtext ——这些小字符错误，往往比语法错误更难定位。