在 VSCode 中配置 LaTeX 环境（Windows）

这是一份在 VSCode 中配置 LaTeX 环境的保姆级教程。我一步步跟着操作，就能成功搭建起专业、高效的学术排版环境。

第一部分：核心概念

• VSCode：是“编辑器”，负责让你方便地写代码。
• TeX 发行版（如 TeX Live/MacTeX）：是“编译器”，负责把你写的代码编译成 PDF

任务：安装一个编译器（TeX Live/MacTeX），并在 VSCode 这个编辑器里安装好控制它的插件（LaTeX Workshop），让两者能顺畅地协同工作。

第二部分：安装 LaTeX 核心引擎（编译器）

通用推荐：TeX Live 2025（跨平台）
TeX Live 是一个完整的 TeX 系统，包含了编译所需的一切，功能最全。

Windows 用户:
1.下载：建议从国内镜像站（如 清华大学 TUNA 镜像站（https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/））下载 texlive.iso 文件（约4~6GB），速度更快。
2. 安装：下载完成后，右键挂载 ISO 镜像文件。在虚拟光驱里找到 install-tl-windows.bat，右键选择 “以管理员身份运行”。

装载中，需要稍等几分钟！！

 

 

3. 设置：安装界面启动后，你只需确认以下两项：
安装路径：默认是 C:\texlive\2025。如果你有多个硬盘，可以改到空间充足的地方（如 D:\TeXLive\2025），路径中不要包含中文或空格。

修改注册表：确保“修改注册表设置”选项是勾选状态。（一般都打了勾）

4. 等待：点击“安装 TeX Live”。这个过程通常需要 1-2 小时，请耐心等待。安装完成后，点击“完成”即可。

出现：欢迎进入Tex Live的世界即下载完成。点击关闭

 

⚡ Windows 备选：MiKTeX（轻量级）
如果硬盘空间不足（TeX Live 需约 8GB），可以选择 MiKTeX（https://miktex.org/）。它的特点是“按需安装”，首次编译时会自动下载缺失的宏包。

1. 下载：访问 MiKTeX 官网 下载 Windows 安装程序。
2. 安装：运行安装程序，建议选择“为所有用户安装”，并按提示操作。为获得最佳体验，推荐选择“完全安装 (Complete)”，避免后续频繁下载宏包。

✅ 验证安装是否成功
安装完成后，请务必验证一下环境。

配置环境变量：进入Windows：找到 TeX Live 的安装目录下的 bin\windows 文件夹（如 C:\texlive\2025\bin\windows），将该路径添加到系统的 PATH 环境变量中，然后重启 VSCode。

Windows：按下 Win + R，输入 cmd 并回车，在打开的终端中输入 xelatex -v。如果能看到版本信息，就说明安装成功。

❀ 第三部分：安装 VSCode 编辑器与插件
1. 安装 VSCode：如果还没安装，请前往 VSCode 官网 下载并安装（微软商店也可，扩展插件里先直接搜索Chinese，下载汉化包重启运行）。
2. 安装核心插件：
　　打开 VSCode，点击左侧的“扩展”图标（或按快捷键 Ctrl+Shift+X ）。
　　在搜索框中输入 LaTeX Workshop，找到由 James Yu 开发的插件，点击“安装”-。这是 VSCode 中最核心的 LaTeX 插件。

🛠️ 第四部分：关键配置 (settings.json)
为了让 LaTeX Workshop 更好地工作（特别是支持中文），我们需要进行一些配置。

1. 打开 settings.json：
　　按快捷键 Ctrl+Shift+P (Windows/Linux) 打开命令面板。
　　输入 Open User Settings (JSON) 并选择它，这会打开你的 VSCode 全局配置文件 settings.json。（亦可直接快捷键F1，搜索User的 settings.json文件）
2. 粘贴配置代码：将以下配置代码完整地复制并粘贴到 settings.json 文件的大括号 { } 中（如果文件里已有其他配置，请确保代码块之间用逗号 , 隔开）。

{
    // ==================== LaTeX Workshop 核心配置 ====================
    // 1. 定义编译工具
    "latex-workshop.latex.tools": [
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-xelatex",   // 关键：使用 xelatex 引擎
                "-outdir=%OUTDIR%",
                "%DOC%"
            ]
        },
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-shell-escape", // 允许执行 shell 命令，部分宏包需要
                "%DOC%"
            ]
        }
    ],
    // 2. 定义编译链 (recipes)
    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk (xelatex)", // 推荐，最自动化
            "tools": ["latexmk"]
        },
        {
            "name": "xelatex -> bibtex -> xelatex*2", // 处理参考文献的链
            "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
        },
        {
            "name": "xelatex",
            "tools": ["xelatex"]
        }
    ],
    // 设置默认编译链为最推荐的 latexmk
    "latex-workshop.latex.recipe.default": "latexmk (xelatex)",
    
    // ==================== 编译与清理设置 ====================
    // 保存文件时自动编译
    "latex-workshop.latex.autoBuild.run": "onSave",
    // 编译失败时自动清理临时文件
    "latex-workshop.latex.autoClean.run": "onFailed",
    // 清理临时文件的类型
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", 
        "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", 
        "*.glg", "*.glo", "*.gls", "*.ist", "*.fls", 
        "*.log", "*.fdb_latexmk", "*.bcf", "*.run.xml"
    ],
    
    // ==================== PDF 预览设置 ====================
    // 在 VSCode 新标签页中打开 PDF
    "latex-workshop.view.pdf.viewer": "tab",
    // 启用正向和反向搜索 (按住 Ctrl/Cmd 并点击PDF可跳转到代码)
    "latex-workshop.view.pdf.internal.synctex.keybinding": "ctrl-click",
    
    // ==================== 辅助功能 ====================
    // 在资源管理器侧边栏显示结构
    "latex-workshop.showContextMenu": true,
    // 生成章节等环境的代码补全提示
    "latex-workshop.intellisense.citation.backend": "biblatex",
    "latex-workshop.intellisense.citation.format": "latex",
    // 让错误弹窗更简洁
    "latex-workshop.message.error.show": false,
    "latex-workshop.message.warning.show": false
}

配置说明：上述代码配置了一个使用 xelatex 引擎的 latexmk 编译链，这对中文支持最好。同时开启了保存时自动编译、内置 PDF 预览等功能。

🐎 第五部分：创建第一个文档并编译

1. 在 VSCode 中新建一个 .tex 文件：在 VSCode 中新建一个文件，保存为 test.tex。
2. 编写测试代码：将以下代码复制到 test.tex 文件中：

% !TEX program = xelatex
\documentclass[12pt]{ctexart}

\title{我的第一个 LaTeX 文档}
\author{你的名字}
\date{\today}

\begin{document}

\maketitle

\section{介绍}
你好，世界！这是我用 VSCode 编写的第一份 LaTeX 文档。

\section{数学公式}
爱因斯坦的质能方程是：$E = mc^2$。

\end{document}

<1>编译文档：
方法一 (推荐)：保存文件 (Ctrl+S)，因为配置了 "onSave"，插件会自动开始编译。
方法二 (手动)：按快捷键 Ctrl+Alt+B (Windows/Linux) 或 Cmd+Alt+B (macOS) 来手动编译。
<2>查看 PDF：

编译成功后，VSCode 的右侧或下方会出现一个 PDF 预览窗口。如果没出现，可以点击 .tex 文件右上角的“放大镜”图标，或按 Ctrl+Alt+V (Windows/Linux) 来打开。

 

 

🚀 第六部分：进阶技巧与常见问题
💡 进阶技巧
　　正向/反向搜索：在生成的 PDF 中，按住 Ctrl (Mac 上是 Cmd) 并用鼠标点击文字，VSCode 会自动跳转到对应的 .tex 代码行。反之，在 .tex 代码中按住 Ctrl/Cmd 点击相应位置，也能跳转到 PDF，这能让修改和校对变得非常方便。
　　模板与代码片段：
模板管理：建立一个文件夹（如 LaTeX_Templates），把你常用的论文、报告模板放进去。写新文档时，直接复制一份作为起点。
代码片段 (Snippets)：在 VSCode 设置中选择“用户代码片段” -> latex.json，可以自定义快捷输入。比如，输入 fig 然后按 Tab，就能自动生成一个 \begin{figure}...\end{figure} 的完整结构。
　　多文件项目：对于长篇文档，可以使用 \input{chapters/intro} 将不同章节放在不同文件中。记得在主文件 .tex 开头用注释 % !TEX root = main.tex 声明根文件，这样无论编辑哪个子文件，编译命令都会指向主文件。
🐛 常见问题排查
　　“latexmk: command not found”：这表明系统没找到 latexmk。这通常是因为 TeX Live 安装时，环境变量没有自动配置好。
　　Windows：找到 TeX Live 的安装目录下的 bin\win32 文件夹（如 C:\texlive\2025\bin\win32），将该路径添加到系统的 PATH 环境变量中，然后重启 VSCode。
　　中文显示为空白或方框：这表示字体未正确加载。请确认 .tex 文件使用了 ctexart 文档类，并改用 xelatex 编译-3。如果问题依旧，可能需要安装或配置中文字体，最简单的方法是使用 \setCJKmainfont{SimSun} 指定一个系统中存在的字体（如 Windows 的“宋体”）。
　　I found no \bibdata 等参考文献报错：请检查.bib文件路径是否正确，并确保编译链中包含了bibtex-。例如，使用上面配置中的 "xelatex -> bibtex -> xelatex*2" 这个编译链。

至此，你的 VSCode + LaTeX 环境就搭建完成了，之后就可以专注于文档的写作和排版了。

在 LaTeX Workshop 插件中，其实就是通过配置实现的“保存时自动编译”-。配置好之后，你每次按 Ctrl+S 保存修改，插件就会自动在后台帮你编译文档，让你几乎立即就能在 PDF 预览中看到最新效果。

参考文章链接：https://blog.csdn.net/qq_42030496/article/details/160142386