VSCode配置LaTeX写作环境 VSCode编译查看PDF教程-VSCode-PHP中文网

latex workshop 是唯一支持编译、预览、跳转全流程的 vscode latex 插件，需确保系统已安装 tex live（含 latexmk 和 xelatex）、path 配置正确、settings.json 显式配置 xelatex recipe 与 -synctex=1、中文文档使用 ctex 类并声明 % !tex root、选用 sumatrapdf（win）或 skim（macos）外部 pdf 查看器。

vscode配置latex写作环境 vscode编译查看pdf教程

LaTeX Workshop 是唯一能真正跑通编译、预览、跳转全流程的插件，其他插件如 LaTeX 或 LaTeX Tools 已长期不维护，装了也白装。

终端里 `latexmk --version` 和 `xelatex --version` 都得能跑通

VSCode 本身不编译 LaTeX，它只调用你系统里装好的命令。插件报 “command not found” 或 “no recipe found”，90% 是这一步没过。

macOS：用 brew install --cask mactex（别用 basictex，它默认不含 latexmk）；装完后确认 /Library/TeX/texbin 在 $PATH 里
Windows：安装 TeX Live 时必须勾选 “Add TeX Live to PATH”；若已装完，手动把类似 C: exlive�4inwin32 加进系统环境变量
Linux：运行 sudo apt install texlive-latex-recommended texlive-latex-extra latexmk，只装 texlive-base 不够
验证方式：关掉 VSCode，从系统终端（不是 VSCode 内置终端）运行 which latexmk 和 which xelatex，两个都必须有输出
VSCode 必须重启（不是重载窗口），才能读取新 PATH

`settings.json` 里必须显式配 `xelatex` recipe 和 `-synctex=1`

默认 recipe 走 pdflatex，中文文档一编译就出方框或报 fontspec 错——这不是插件问题，是引擎硬性不匹配。

VSCode

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

下载

在 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 点击跳不回源码；-interaction=nonstopmode 防止编译卡死在报错处
别同时启用其他 LaTeX 插件，会冲突

中文文档必须用 `ctex` 类 + `% !TEX root = main.tex` 声明主文件

光写 usepackage{ctex} 不行，documentclass[UTF8]{ctexart} 才是正解。漏掉声明主文件，cite{} 和 ef{} 全是 ??。

主 .tex 文件第一行加：% !TEX root = main.tex（哪怕就是当前文件，也得写）
导言区用 documentclass[UTF8]{ctexart}（或 ctexrep/ctexbook），别用 article + 手动加 xeCJK
字体不用额外配：ctex 默认加载系统中文字体；若需微调，再加 setmainfont{Noto Serif CJK SC}（macOS/Linux）或 setmainfont{"Microsoft YaHei"}（Windows，带空格必须引号）
如果用了 input{ch1.tex} 或 include{data/figs}，路径必须对，且这些子文件不能单独编译——插件只认 root 声明的那个文件

PDF 不自动刷新？换 `SumatraPDF`（Windows）或 `Skim`（macOS）

VSCode 内置 PDF 查看器不支持热重载，且 synctex 反向搜索会锁住文件。Adobe Reader、Foxit 等通用阅读器也不行。

Windows：装 SumatraPDF，在设置里填路径："latex-workshop.view.pdf.external.viewer.command": "C:\Program Files\SumatraPDF\SumatraPDF.exe"
macOS：装 Skim，路径设为 /Applications/Skim.app/Contents/MacOS/Skim
关闭内置预览："latex-workshop.view.pdf.viewer": "external"
别碰 latex-workshop.view.pdf.internal.synctex.afterBuild.enabled——关了它虽能强制刷新，但反向跳转彻底失效
首次编译建议手动按 Ctrl+Alt+B（Win/Linux）或 Cmd+Alt+B（macOS），别依赖保存即编译；有些模板（如 IEEEtran）需要多遍跑 bibtex 才出参考文献