用 Dev Container 配置 VS Code + LaTeX 环境

2025-09-23

Table of Contents

这套配置用 Dev Container¹ 管理 LaTeX 环境，用 Git 同步项目。拉取仓库后，在容器中打开即可编译。

# 安装编辑器扩展

在 Cursor 或 VSCode 中，安装官方扩展 Dev Containers

假设你已有一个 LaTeX 项目文件夹（新建空文件夹也可以），跟着做就能用：

打开项目的终端（VSCode/Cursor 内置终端即可），执行以下命令，将预配置好的容器环境作为「子模块」引入项目（子模块不干扰主项目文件，方便后续更新）：

git submodule add https://github.com/paperdebugger-bot/latex-devcontainer.git .devcontainer

如果你的项目还没初始化 Git（git init），也可以直接下载配置文件解压到 .devcontainer 文件夹：latex-devcontainer.zip

按下快捷键 Ctrl + Shift + P（macOS 是 ⌘ + ⇧ + P），在弹出的命令面板中输入 Reload Window 并执行，让编辑器识别新添加的容器配置。

重载后，编辑器会自动弹出提示「是否在 Dev Container 中打开项目」，点击 Reopen in Container；

接下来会让你选择容器版本，直接选 full 即可 —— 等待 3-5 分钟（首次构建需下载镜像，后续会快很多），环境就搭建完成了！

🎉 完成后你会获得什么？

上面推荐的 full 版本是「省事优先」，但如果你的项目轻量化、或想节省磁盘空间，可以选其他版本。核心区别在于「预装的 TeX 发行版」不同：

容器版本	核心 TeX 发行版	特点	适合场景
full	TeX Live Full	预装较完整的宏包（约 6GB），减少手动安装	复杂论文、自定义模板、不想处理宏包问题
tiny	TinyTeX³	轻量版（约 1GB），默认含 200+ 常用宏包	简单报告、常规学术论文（缺包时需手动 `tlmgr install 宏包名`）
nano	Tectonic⁴	零配置引擎，自动处理依赖	快速写 Demo、极简文档（兼容性略弱，复杂宏包可能不支持）

💡 切换方法：
在启动容器时，选择对应版本即可；如果已启动容器，可通过 Ctrl + Shift + P → Dev Containers: Rebuild Container 重新选择版本。

Q1：构建容器时速度很慢？

A1： 首次构建需下载大镜像，建议换国内 Docker 镜像源（比如阿里云、网易云镜像），或在网络较好的环境下操作。

Q2：编译中文文档乱码？

A2： full 和 tiny 版本已预装 xeCJK 宏包，编译时选择 xelatex 引擎即可（LaTeX Workshop 已默认配置）。

Q3：如何更新容器配置？

A3： 如果远程仓库的 latex-devcontainer 有更新，可在项目终端执行：

git pull --recurse-submodules
git submodule update --recursive --remote

然后重建容器（Rebuild Container）即可应用更新。

这套方案我自己用了半年，从写技术报告到学术论文，没再遇到过一次「环境报错」。如果你也厌倦了配置 LaTeX 环境，不妨试试。