这篇文章为「有洁癖的程序员」和「不想折腾环境的写作者」，提供一套开箱即用的容器化 LaTeX 方案：用容器隔离环境，用 Git 同步项目，做到「拉仓库 → 打开容器 → 立即编译」，彻底告别环境配置焦虑。

你可以随时随地使用 Git 同步你的项目，随用随走，无需担心环境问题。同时，你也可以放心大胆地让 Claude Code、Codex 帮你写 LaTeX 代码，不担心执行危险指令（请做好 git push protect）

# 你只需要准备 1 件事

无需安装复杂的 TeX 发行版、不用配置系统环境变量，唯一要做的就是：

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

# 三个步骤，从 0 到能写 LaTeX

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

## Step 1 引入 Dev Container 配置

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

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

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

## Step 2 重载编辑器窗口

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

## Step 3 启动容器并使用

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

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

🎉 完成后你会获得什么？

• 预装 TeX Live Full 发行版（几乎包含所有宏包，不用手动装）；
• 自带 LaTeX Workshop 插件（VSCode 最好用的 LaTeX 插件，支持实时预览、一键编译）¹；
• 配置好的 PDF 预览 功能；
• 干净的终端环境（可直接用 pdflatex xelatex 等命令）。

# 进阶选择：不同的容器版本怎么挑？

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

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

# 为什么推荐用 Dev Container⁴？

很多人会问：「我直接在本地装 TeX Live 不行吗？」

当然可以，但 Dev Container 解决了 3 个核心痛点：

痛点 1：环境隔离，不污染系统

容器是独立的「沙盒」，所有 TeX 依赖、插件都装在容器里，不会修改你本地的系统配置（比如不会和 Python、Java 等环境冲突）。想删除环境？直接删除容器即可，不留任何残留。

痛点 2：跨设备同步，随用随走

把项目和 .devcontainer 文件夹一起用 Git 管理，换电脑时只需「拉取仓库 → 打开容器」，10 分钟内就能恢复一模一样的写作环境——再也不用在公司电脑配一次、家里电脑又配一次。

痛点 3：安全可控，放心用 AI 辅助

现在很多人用 Claude Code、Codex 生成 LaTeX 代码，这些工具可能会输出 sudo 等危险命令。而容器内的操作不会影响本地系统，相当于加了一层「安全防护」（注意：仍需做好 Git 提交保护，避免泄露敏感内容）。

# 常见问题 Q&A

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 环境，不妨试试。