这是一份在 VSCode 中配置 LaTeX 环境的保姆级教程。我的目标是确保即使是零基础的新手，只要能一步步跟着操作，就一定能成功搭建起专业、高效的学术排版环境。
🎯 第一部分：核心概念------我们要做什么？
在开始前，请先分清两个关键概念-48：
- VSCode：是"编辑器"，负责让你方便地写代码。
- TeX 发行版（如 TeX Live/MacTeX）：是"编译器"，负责把你写的代码编译成 PDF。
我们的任务就是：安装一个编译器（TeX Live/MacTeX），并在 VSCode 这个编辑器里安装好控制它的插件（LaTeX Workshop），让两者能顺畅地协同工作。
💻 第二部分：安装 LaTeX 核心引擎（编译器）
这是最关键的一步。请根据你的操作系统，从下方选择一个安装。
📥 通用推荐：TeX Live 2025（跨平台）
TeX Live 是一个完整的 TeX 系统，包含了编译所需的一切，功能最全-1。
-
Windows 用户 :
- 下载 ：建议从国内镜像站（如 清华大学 TUNA 镜像站）下载
texlive.iso文件（约4GB），速度更快-27。 - 安装 ：下载完成后，右键挂载 ISO 镜像文件。在虚拟光驱里找到
install-tl-windows.bat，右键选择 "以管理员身份运行" -27。 - 设置 ：安装界面启动后，你只需确认以下两项：
- 安装路径 ：默认是
C:\texlive\2025。如果你有多个硬盘，可以改到空间充足的地方（如D:\TeXLive\2025），路径中 不要包含中文或空格 -27。 - 修改注册表：确保"修改注册表设置"选项是勾选状态。
- 安装路径 ：默认是
- 等待 ：点击"安装 TeX Live"。这个过程通常需要 1-2 小时 ，请耐心等待。安装完成后，点击"完成"即可-27。
- 下载 ：建议从国内镜像站（如 清华大学 TUNA 镜像站）下载
-
macOS 用户 :
-
Linux (Ubuntu/Debian) 用户 :
1.sudo apt update sudo apt install texlive-full- 其他发行版：请使用对应的包管理器命令。
⚡ Windows 备选：MiKTeX（轻量级）
如果硬盘空间不足（TeX Live 需约 8GB），可以选择 MiKTeX。它的特点是"按需安装"，首次编译时会自动下载缺失的宏包-1。
- 下载 ：访问 MiKTeX 官网 下载 Windows 安装程序。
- 安装 ：运行安装程序，建议选择"为所有用户安装"，并按提示操作。为获得最佳体验，推荐选择"完全安装 (Complete) "，避免后续频繁下载宏包-1。
✅ 验证安装是否成功
安装完成后，请务必验证一下环境。
- Windows ：按下
Win + R，输入cmd并回车，在打开的终端中输入xelatex -v。如果能看到版本信息，就说明安装成功了-1。 - macOS/Linux ：打开"终端"（Terminal），输入同样的
xelatex -v命令进行验证。
🔌 第三部分：安装 VSCode 编辑器与插件
- 安装 VSCode ：如果还没安装，请前往 VSCode 官网 下载并安装。
- 安装核心插件 ：
🛠️ 第四部分：关键配置 (settings.json)
为了让 LaTeX Workshop 更好地工作（特别是支持中文），我们需要进行一些配置。
- 打开 settings.json ：
- 按快捷键
Ctrl+Shift+P(Windows/Linux) 或Cmd+Shift+P(macOS) 打开命令面板-12。 - 输入
Open User Settings (JSON)并选择它，这会打开你的 VSCode 全局配置文件settings.json。
- 按快捷键
- 粘贴配置代码 ：将以下配置代码完整地 复制并粘贴到
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编译链，这对中文支持最好--45。同时开启了保存时自动编译、内置 PDF 预览等功能-6。
✍️ 第五部分：创建第一个文档并编译
% !TEX program = xelatex
\documentclass[12pt]{ctexart}
\title{我的第一个 LaTeX 文档}
\author{你的名字}
\date{\today}
\begin{document}
\maketitle
\section{介绍}
你好，世界！这是我用 VSCode 编写的第一份 LaTeX 文档。
\section{数学公式}
爱因斯坦的质能方程是：$E = mc^2$。
\end{document}- 编译文档 ：
- 方法一 (推荐) ：保存文件 (
Ctrl+S)，因为配置了"onSave"，插件会自动开始编译。 - 方法二 (手动) ：按快捷键
Ctrl+Alt+B(Windows/Linux) 或Cmd+Alt+B(macOS) 来手动编译-5。
- 方法一 (推荐) ：保存文件 (
- 查看 PDF ：编译成功后，VSCode 的右侧或下方会出现一个 PDF 预览窗口-6。如果没出现，可以点击
.tex文件右上角的"放大镜"图标，或按Ctrl+Alt+V(Windows/Linux) /Cmd+Alt+V(macOS) 来打开-6。
🚀 第六部分：进阶技巧与常见问题
💡 进阶技巧
- 正向/反向搜索 ：在生成的 PDF 中，按住
Ctrl(Mac 上是Cmd) 并用鼠标点击文字，VSCode 会自动跳转到对应的.tex代码行。反之，在.tex代码中按住Ctrl/Cmd点击相应位置，也能跳转到 PDF，这能让修改和校对变得非常方便-5-6。 - 模板与代码片段 ：
- 多文件项目 ：对于长篇文档，可以使用
\input{chapters/intro}将不同章节放在不同文件中。记得在主文件.tex开头用注释% !TEX root = main.tex声明根文件，这样无论编辑哪个子文件，编译命令都会指向主文件-5。
🐛 常见问题排查
- "
latexmk: command not found" ：这表明系统没找到latexmk。这通常是因为 TeX Live 安装时，环境变量没有自动配置好。- Windows ：找到 TeX Live 的安装目录下的
bin\win32文件夹（如C:\texlive\2025\bin\win32），将该路径添加到系统的 PATH 环境变量中，然后重启 VSCode-27。 - macOS/Linux ：在终端中运行
echo $PATH，确认 TeX Live 的bin路径（如/usr/local/texlive/2025/bin/x86_64-linux）是否在其中。如果没有，需要手动将其添加到你的 shell 配置文件中（如.bashrc或.zshrc）。
- Windows ：找到 TeX Live 的安装目录下的
- 中文显示为空白或方框 ：这表示字体未正确加载。请确认
.tex文件使用了ctexart文档类，并改用xelatex编译-3。如果问题依旧，可能需要安装或配置中文字体，最简单的方法是使用\setCJKmainfont{SimSun}指定一个系统中存在的字体（如 Windows 的"宋体"）。 I found no \bibdata等参考文献报错 ：请检查.bib文件路径是否正确，并确保编译链中包含了bibtex-。例如，使用上面配置中的"xelatex -> bibtex -> xelatex*2"这个编译链。
至此，你的 VSCode + LaTeX 环境就搭建完成了，之后就可以专注于文档的写作和排版了。
在 LaTeX Workshop 插件中，其实就是通过配置实现的"保存时自动编译 "-。配置好之后，你每次按 Ctrl+S (或 Cmd+S) 保存修改，插件就会自动在后台帮你编译文档，让你几乎立即就能在 PDF 预览中看到最新效果-。