如何在vscode中编写LaTeX文档_从环境配置到编译输出的指南【教程】

VS Code可通过安装TeX Live和LaTeX Workshop扩展并正确配置编译链、中文支持及路径，实现专业LaTeX写作；关键在于装对工具、配准命令、避开编码与路径陷阱。

VS Code 本身不内置 LaTeX 支持，但通过扩展 + 外部编译器组合，完全可以替代传统编辑器（如 TeX Live + TeXworks）完成日常写作。关键不是“能不能”，而是「装对扩展、配对命令、避开路径和编码坑」。

安装 LaTeX 工具链：TeX Live（windows/macOS/linux 通用）

VS Code 只是编辑器，latexmk、xelatex、pdflatex 等命令必须由系统级 LaTeX 发行版提供。推荐直接安装 TeX Live（而非 MiKTeX），因其跨平台行为更一致、宏包更新更及时。

• Windows：下载 install-tl-windows.exe，勾选「添加 PATH」，安装时建议自定义路径（如 C:texlive2024），避免空格或中文路径
• macOS：用 brew install --cask mactex（完整版）或 brew install texlive（精简版）；后者需手动补装常用宏包（如 fontspec、polyglossia）
• Linux（ubuntu/debian）：sudo apt install texlive-full（或按需安装 texlive-latex-recommended + texlive-fonts-recommended）
• 安装后在终端运行 latexmk --version 或 xelatex --version，确认返回版本号，否则 VS Code 无法调用

配置 LaTeX Workshop 扩展：核心参数与编译链设置

LaTeX Workshop 是目前最成熟的 VS Code LaTeX 扩展，但默认配置不适用于中文或 XeLaTeX 场景。重点调整以下三项：

• 在 VS Code 设置中搜索 latex-workshop.latex.recipe.default，设为 first（让插件自动选第一个可用 recipe）
• 修改 latex-workshop.latex.recipes：添加自定义 recipe，例如用 xelatex 编译中文文档：

  [{"name": "xelatex","tools": ["xelatex"]},{"name": "latexmk","tools": ["latexmk"]}]

• 配置 latex-workshop.latex.tools：确保 xelatex 工具的 args 包含 -synctex=1 和 -interaction=nonstopmode，否则编译中断或跳转失效
• 若项目含 .bib 文件，需额外添加 bibtex 或 biber 工具，并在 recipe 中按顺序声明（如 ["xelatex", "biber", "xelatex", "xelatex"]）

中文支持与字体配置：绕过 fontspec 报错的关键点

用 xelatex 编译中文文档时，fontspec 报错（如 Font zf@basefont="Noto Serif CJK SC" at 10.0pt not loadable）几乎必现，根源是字体名未被正确识别或系统未安装对应字体。

• 不要硬写系统字体全名（如 "Source Han Serif SC"），改用 AutoFakeBold + Mapping=tex-text 等容错参数
• 推荐方案：用 ctex 宏包替代手动加载 fontspec，它自动适配中文字体并处理标点、章节编号等：

  documentclass[UTF8]{ctexart}

• Windows 用户若仍报错，检查是否安装了「思源宋体」或「Noto Serif CJK」；macos 用户可直接用 "PingFang SC" 或 "Heiti SC"；Linux 需手动安装 fonts-noto-cjk 并刷新缓存（fc-cache -fv）
• 务必在导言区末尾加 setmainfont{Noto Serif CJK SC}（或对应字体），且该语句不能出现在 ctex 加载前

编译失败常见原因与快速定位方法

VS Code 底部状态栏显示「Recipe terminated with Error」时，别急着重装，先看三处输出：

• 打开 LaTeX Workshop 输出面板（Ctrl+Shift+P → LaTeX Workshop: View Log Messages），重点查 ! undefined control sequence 或 File ended while scanning use of textbf 这类错误——通常是宏包缺失或括号不匹配
• 检查当前打开的文件是否为 .tex 主文档（非子文件），且文件名不含空格、中文或特殊符号（如 report v2.tex 会触发 latexmk 路径解析失败）
• 若报错 Cannot read Property 'Length' of undefined，大概率是 settings.json 中 latex-workshop.latex.outDir 路径用了相对路径（如 ./out）但目录不存在，改为绝对路径或删掉该项让插件自动创建
• 编译卡住不动？关掉所有其他 .log 或 .aux 文件标签页，它们可能被锁住导致 latexmk 无法覆盖写入

最常被忽略的是：VS Code 的集成终端（Terminal）和外部终端（如 Windows Terminal）的环境变量不同——PATH 里没包含 TeX Live 的 bin 目录，导致插件找不到 xelatex。此时要么重启 VS Code（让它读取系统 PATH），要么在 settings.json 中显式指定 latex-workshop.latex.tools 的 path 字段。