Docker 化 TeX Live：彻底解决 LaTeX 环境不一致问题

Docker 部署 TeX Live 这件事，听起来像是运维该干的活，但真做下来你会发现，它解决的是每个写论文的人都会撞上的问题：环境不一致。同一个 main.tex，在自己电脑上编译得好好的，拷到导师机器上就报! LaTeX Error: File 'xxx.sty' not found；或者换一个 TeX Live 版本，正文排版和参考文献格式全变了。与其到处装套装、调 PATH，不如把 TeX Live 整体扔进 Docker 容器里，让编译环境跟着项目走。

这是给谁的方案？凡是需要长期用 LaTeX 写论文、写报告、做简历的人，都值得搞一套。尤其是这几类场景：毕业季反复改稿的学生、需要和同学导师共享编译环境的小团队、想把论文编译接进自动构建流程的“讲究人”。你不需要懂太深的 Docker 原理，会敲命令就能用。下面我就按自己实际搭这套平台的完整链路，从为什么这么做、镜像怎么选，到怎么和编辑器配合、遇到问题怎么排，一步一步讲清楚。

1. 为什么要把 LaTeX 编译环境容器化

1.1 本地安装 TeX Live 的三个痛点

先说说本地装 TeX Live 有多折腾。完整版安装包动辄四五个 GB，下载回来以后，安装时间也够你冲好几杯咖啡。但这只是开始，真正麻烦的是后面：

第一个痛点是版本碎片化。有人用 TeX Live 2021，有人用 2023，还有人电脑里躺着十几年前的 CTEX 套装。LaTeX 宏包更新很快，不同版本对同一段代码的处理结果可能完全不同。最典型的例子是参考文献样式，同一个.bst文件在旧版本上正常，换到新版就多了一个空格或者改了对齐方式。

第二个痛点是“我编译通过”不等于“你编译通过”。团队协作写论文的时候，A 同学用的是 macOS + TeX Live 2023，B 同学是 Windows + TeX Live 2021，中间再夹一个用 Overleaf 的。每次同步代码，总有人卡在环境问题上，最后只能靠把 PDF 直接发群里来“协作”，这完全违背了 LaTeX 版本管理的优势。

第三个痛点是清理不干净。本地安装的 TeX Live 卸载起来比较麻烦，装完以后 PATH、字体缓存、用户目录下的.texlive文件夹，很容易留一堆残渣。如果你和我一样喜欢“干净的系统”，时间长了就会很抓狂。

1.2 容器化方案的核心优势

把 TeX Live 装进 Docker 后，以上三个痛点基本全消。首先，编译环境是“一次性”的，镜像定义好了，无论你换几台电脑，docker run起来就是一模一样的工具链。年初我换工作电脑，旧电脑里的 TeX Live 配置没迁移，新电脑上只要一条docker pull，我所有的论文项目直接能编译。

其次，版本可以被精确锁定。在团队项目里，我们把texlive/texlive:2023写进Dockerfile或docker-compose.yml，所有人都用这一个镜像。再也不用问“你 LaTeX 版本是多少”，因为大家跑的是同一个容器。这种做法，和你在生产环境用 Docker 部署 MySQL、Redis、以及各种模型服务是同一个思路——环境隔离加可复现，只是这次被隔离的是一个编译器而已。

最后是对宿主机零污染。Docker 只是在宿主机上跑了一个隔离环境，除了镜像文件本身，不会在系统目录里乱放东西。哪天你不想用 LaTeX 了，docker rmi一下，干干净净。我在公司内部做过一次统计，一个团队如果把 TeX Live 环境从个人电脑统一收编到 Docker 镜像里，光解决“环境问题”的时间每周至少能省出一两个小时。

1.3 不是所有人都需要容器化

当然，得说句公道话：不是所有用户都需要这套方案。如果你只是偶尔写一份两页的课程作业，本地装一个 lightweight 版本或者直接用在线编辑器，可能更省事。容器化真正适合的是中重度用户：高频写长文档、对版本有严格要求、多人协作、或者需要把编译接入脚本和流水线的。判断标准很简单——如果你已经开始为“环境不一致”头疼了，那就是时候上了。

2. 镜像选择与部署前准备

2.1 官方镜像怎么选才稳

Docker Hub 上有多个 TeX Live 相关镜像，我用下来最稳妥的是官方维护的texlive/texlive。这个镜像由 TeX Live 官方发布，里面的宏包与工具链完整性高，日常写论文需要的工具几乎都已经预装好，不需要额外折腾。它的 tag 策略按年度发布，比如texlive/texlive:2024、texlive/texlive:2025，当然也会有latest指向最新版本。顺便说一句，TeX Live 本身按年度发版，所以你看到 2026 这样的年度标签也不用奇怪，关键是根据你的复现需求选择具体年份即可。

这里我强烈建议：写论文不是为了“追新”，能用就别老换。我的习惯是锁定一个特定年份的 tag，比如texlive/texlive:2025，而不是追着latest跑。因为论文写到后半段，宏包版本的稳定性比新功能重要得多。换个版本导致参考文献格式变化，这种坑我踩过，真的非常折腾。

如果你觉得完整版镜像体积太大，也可以考虑自定义精简版。TeX Live 的安装器支持 scheme 级别的裁剪，比如只装scheme-small或按宏包集合定制。但说实话，对大多数论文场景，我建议直接用完整版。你自己裁剪确实能省几个 GB，但日后缺宏包的可能性大大增加，那种“编译到一半报缺sty文件”的体验更让人崩溃。

2.2 宿主机需要准备什么

在部署之前，宿主机要先装好 Docker。Windows 和 macOS 上一般用 Docker Desktop，Linux 直接用 Docker Engine。这里我不展开 Docker 安装细节，但有一个坑提前说：Windows 上如果启动 Docker Desktop 时提示virtualization support not detected，大概率是因为 BIOS 里的虚拟化功能没开，或者 Hyper-V / WSL2 功能没启用。解决方法是进 BIOS 开启 Intel VT-x 或 AMD-V，然后在 Windows 功能里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”，重启后再启动 Docker Desktop。

磁盘空间也要预留出来。texlive/texlive镜像解压后体积不小，完整版镜像一般在 7 GB 到 10 GB 左右。如果电脑磁盘本来就紧张，可以先清理一下 Docker 的存量镜像，或者考虑使用精简版做二次定制。

最后是一个目录规划的问题。建议在你的工作区里建立一个统一的论文项目目录，里面就是普通的 LaTeX 工程结构：main.tex、figures/、bib/、fonts/等。容器挂载时把整个项目目录映射进去，这样源码和生成的 PDF 都留在宿主机上，容器本身随时可以丢弃重建。

提示：容器是临时、可丢弃的。你的论文源文件、图标、参考文献数据库，永远只放在宿主机目录。容器里只跑编译，不存任何“重要数据”。

3. 从拉取镜像到跑通第一次编译

3.1 拉取镜像并验证工具链

准备工作做完，第一步就是拉取镜像。在终端里执行：

docker pull texlive/texlive:latest

镜像体积大，首次拉取时间取决于网络环境，耐心等就行。拉取完成后，先验证一下容器内的 LaTeX 工具链是否正常：

docker run --rm texlive/texlive:latest latex --version

如果能看到pdfTeX 3.141592653之类的版本信息，说明工具链已经可用。这时候你可以再顺手看一下 xelatex 和 latexmk 是否都在：

docker run --rm texlive/texlive:latest which xelatex latexmk bibtex

正常情况下三个路径都会打印出来。如果缺了什么，说明你拉取的镜像不是完整版，需要重新确认 tag 或者换官方完整镜像。

3.2 在论文目录里跑通编译

工具链验证通过后，挂载你的论文项目目录进行编译。假设你在宿主机上的论文项目位于~/paper，里面有一个main.tex，执行：

cd ~/paper docker run --rm -v "$(pwd):/work" -w /work texlive/texlive:latest latexmk -xelatex main.tex

这条命令有几个关键点要讲一下。-v "$(pwd):/work"是把当前目录挂载到容器的/work，-w /work是设置容器内的工作目录，这样latexmk会在/work下找到main.tex并生成辅助文件和 PDF。编译结束后，容器退出并删除（--rm），但~/paper目录下已经多了一个main.pdf。

我用-xelatex而不是默认的pdflatex，原因很简单：xelatex 对中文等 Unicode 字符的支持更友好，配合ctex宏包可以直接排版中文论文，免去转码和字体配置的麻烦。如果你写的是纯英文文档，用pdflatex或者lualatex也都没问题，但为了“一次配置到处写中文”，我建议统一用 xelatex。

latexmk是一个自动编译驱动工具，它会自动判断需要跑几遍 LaTeX、什么时候需要调 bibtex、什么时候需要再补一遍编译。手写latex -> bibtex -> latex -> latex四个步骤的时代真的可以过去了。

3.3 中文排版与字体问题的三种解决方案

使用 xelatex + ctex 宏包是中文论文常见的方案，很多中文模板本身也是基于 ctex 的。比如你的文档导言区这样写：

\documentclass[UTF8]{ctexart} \begin{document} 你好，世界！ \end{document}

但这里有一个必须正视的问题：texlive/texlive官方镜像默认不包含中文字体。如果你的文档只是用了 ctex 宏包，但容器里没有可用的中文字体文件，编译结果就是一片方块或者乱码。这是中文用户最容易踩的坑，我自己也在这个问题上耗过一个晚上。

我实践下来有三条可靠的路子，按推荐程度排序：

第一种，把宿主机字体目录挂载进容器。Linux 用户可以挂载/usr/share/fonts，Windows 用户可以把C:\Windows\Fonts挂载进去，macOS 用户挂载/System/Library/Fonts和/Library/Fonts。挂载命令类似：

docker run --rm -v "$(pwd):/work" -w /work \ -v "/System/Library/Fonts:/fonts:ro" \ -v "/Library/Fonts:/fonts2:ro" \ texlive/texlive:latest latexmk -xelatex main.tex

第二种，把字体文件直接放到项目目录里，随项目一起挂载。在项目下建一个fonts/目录，放入要用的中文字体，比如思源宋体、宋体、黑体，然后挂载进容器：

docker run --rm -v "$(pwd):/work" -w /work \ -v "$(pwd)/fonts:/usr/local/share/fonts:ro" \ texlive/texlive:latest latexmk -xelatex main.tex

这个方案的好处是“字体跟着项目走”，换电脑也不用重新配字体，非常适合团队协作。

第三种，基于官方镜像构建一个已经装好中文字体的自定义镜像。这个方法从根本上解决问题，但需要写 Dockerfile，我会在下一节完整展开。

注意：如果你在 Windows 上把C:\Windows\Fonts挂载进容器，文件名大小写和权限问题可能让人头疼。建议只挂载你明确需要的字体文件，或者直接把字体复制到项目fonts/目录里，这样最省心。

3.4 用 Dockerfile 固化自己的编译环境

如果你只是偶尔编一次，前面的临时挂载方案已经足够。但如果你想长期稳定使用，我更推荐写一个自己的 Dockerfile，把字体、常用宏包、环境变量一次性固化下来。我的 Dockerfile 大概长这样：

FROM texlive/texlive:2025 # 安装常用中文字体（以 Noto CJK 为例） RUN apt-get update && \ apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra && \ rm -rf /var/lib/apt/lists/* # 设置工作目录 WORKDIR /work # 默认入口：进入容器后直接停在 /work CMD ["bash"]

构建命令：

docker build -t my-latex:2025 .

构建完成后，以后编译论文只需要：

docker run --rm -v "$(pwd):/work" -w /work my-latex:2025 latexmk -xelatex main.tex

因为字体已经装进了镜像，ctex宏包会通过fontspec自动检测并调用系统中文字体，基本不用再手动指定字体文件。镜像体积虽然又大了一些，但对论文写作来说，稳定和“无脑复用”更重要。

3.5 顺手解决文件权限问题

用docker run编译有一个容易忽略的细节：容器内默认是 root 用户，生成的.aux、.log、.pdf文件在宿主机上的所有者是 root。如果你后面想在宿主机上手动清理这些文件，可能会碰到Permission denied。解决办法是编译时指定当前用户：

docker run --rm -v "$(pwd):/work" -w /work \ --user "$(id -u):$(id -g)" \ my-latex:2025 latexmk -xelatex main.tex

$(id -u)和$(id -g)会把当前用户的 UID 和 GID 传进去，生成的临时文件就归当前用户所有了。这个细节在 Linux 和 macOS 上很实用，Windows 下用 Git Bash 也可以这样写。

4. 与编辑器配合：VS Code + LaTeX Workshop

4.1 为什么推荐 LaTeX Workshop

终端里能出 PDF，但写论文终究需要编辑器。VS Code 加 LaTeX Workshop 是我目前用过最顺手的组合。这个插件能提供语法高亮、自动补全、文档结构树、编译状态显示、错误定位这些能力，而且它会记住你上次编译用的引擎，打开项目就能一键编译。

更妙的是，LaTeX Workshop 支持自定义编译工具链。也就是说，我们可以不安装本地 TeX Live，而是让它调用 Docker 容器里的latexmk来编译。这样既保留了编辑器的图形化体验，又享受了容器环境的干净和统一。

如果你不想在本机装 VS Code 之外的任何 LaTeX 发行版，这个方案就是为你准备的。只要电脑上有 Docker，再大的 LaTeX 项目都能编。

4.2 配置 LaTeX Workshop 调用 Docker 编译器

在 VS Code 里打开你的 LaTeX 项目，按下Ctrl+Shift+P（Mac 上是Cmd+Shift+P）打开命令面板，输入 “settings”，打开用户设置 JSON。然后写入如下配置：

"latex-workshop.latex.tools": [ { "name": "docker_latexmk", "command": "docker", "args": [ "run", "--rm", "-v", "%DIR%:/work", "-w", "/work", "--user", "1000:1000", "my-latex:2025", "latexmk", "-xelatex", "-interaction=nonstopmode", "%DOC%" ] } ], "latex-workshop.latex.recipes": [ { "name": "Docker Compile", "tools": ["docker_latexmk"] } ]

这里有两个 LaTeX Workshop 内置的魔法变量：%DIR%表示当前 LaTeX 文件所在目录，%DOC%表示当前主文档文件名。配置好之后，在main.tex里按Ctrl+Alt+B（或者在命令面板里选 “Build LaTeX project”），插件就会执行这条 Docker 编译命令。

需要特别提醒的是路径处理。在 Windows 上，%DIR%可能是C:\Users\...这样的反斜杠路径，直接传给 Docker 挂载可能会出问题。我个人是在 Git Bash 里启动 VS Code，路径一般不会出问题；如果你用 PowerShell 遇到挂载失败，考虑把项目路径放到一个没有空格的目录下，或者升级到最新版 LaTeX Workshop，它对路径转义的兼容性好一些。

技巧：-interaction=nonstopmode这个参数最好加上。否则 LaTeX 在遇到错误时可能停下来等待输入，而在 Docker 非交互环境下，编译会卡住直到超时。

4.3 自动编译、PDF 预览与辅助文件清理

LaTeX Workshop 有一个很方便的功能是自动编译：修改保存后自动触发编译。你可以在 settings.json 里加：

"latex-workshop.latex.autoBuild.run": "onSave"

这样每次保存main.tex，项目就会自动在容器里编译一次。配合 Workshop 内置的 PDF 预览，页面会同步刷新，基本就是“边写边看效果”的状态。早期我把 PDF 留在外部阅读器里看，每次都要手动切换窗口，体验很差。后来直接用内置的 tab 预览，专注力提升不少。

清理临时文件也很简单。LaTeX 编译会生成一堆.aux、.log、.out、.toc之类的辅助文件。我习惯在终端里用 docker 执行清理：

docker run --rm -v "$(pwd):/work" -w /work my-latex:2025 latexmk -c

latexmk -c只清理辅助文件，不删除最终的 PDF。这是我在多次误删 PDF 之后学到的教训——千万不要用-C，大写 C 会把 PDF 也一起删掉。

5. 论文编译常见报错与排查实录

5.1 BibTeX 版本信息出现后没有参考文献

很多人在日志里看到类似This is BibTeX, Version 0.99d (TeX Live 2022)的输出，然后发现 PDF 里没有参考文献列表。这其实不是 BibTeX 本身报错，而是编译流程没有完整执行。正确引用参考文献的完整流程是：LaTeX 编译生成.aux文件，BibTeX 读取.aux里的\citation和\bibstyle生成.bbl，再跑两遍 LaTeX 让引用交叉生效。

如果你手动用docker run编译，而没有把bibtex步骤加进去，自然不会有参考文献。使用latexmk的时候，它会自动分析项目结构，判断是否需要调用 bibtex。但前提是你的main.tex里正确引用了.bib文件，比如：

\bibliography{refs} \bibliographystyle{plain}

如果 bibtex 跑完还是没生成参考文献，查看日志里有没有I couldn't open database file refs.bib之类的提示。这种问题多半是.bib文件路径不对或者没有挂载进容器。检查一下你的挂载目录，确认 refs.bib 确实在项目根目录。

5.2 中文变方块或乱码

中文显示成方块，绝大多数原因是容器里没有中文字体，而不是文档代码有问题。先确认你是不是用 xelatex 编译；再用fc-list :lang=zh在容器里查看中文字体：

docker run --rm my-latex:2025 fc-list :lang=zh

如果输出为空，就说明容器里没有可用的中文字体，回到前面第 3.3 节，挂载字体或者用构建了中文字体的自定义镜像。另外，也检查一下main.tex的编码，必须是无 BOM 的 UTF-8。Windows 上如果用过自带的记事本存文件，默认可能是带 BOM 的 UTF-8，这在某些情况下会导致第一个字符乱码。建议用 VS Code 重新保存为 UTF-8 without BOM，问题迎刃而解。

5.3 Docker Desktop 启动失败：提示 virtualization support not detected

这个报错几乎已经成了 Windows 装 Docker 的“第一道坎”。报错信息里直接写明virtualization support not detected，意思是虚拟化没有被检测到。排查顺序很固定：先重启进入 BIOS/UEFI 设置，找到 Intel Virtualization Technology（Intel 平台）或 SVM Mode（AMD 平台），确认设置为 Enabled；保存退出后，再去 Windows 的“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”；然后重启电脑。如果还是不行，检查 Windows 是否有更新或第三方安全软件拦截了 Hyper-V 服务。

这个坑我没有直接遇到过（我主要在 macOS 和 Linux 上跑 Docker），但帮同事排查过好几次，基本上都是 BIOS 虚拟化没开。优先检查 BIOS 就能解决，别再重装 Docker Desktop 了。

5.4 日常 LaTeX 语法问题速查：希腊字母、换行符、弧符号

写论文时还经常碰到一些“基础但一查再查”的语法点。既然我们的编译平台搭好了，顺手把这些常见语法梳理一下，不用每次临时搜。

希腊字母：在数学模式下用反斜杠加英文名称，例如\alpha、\beta、\gamma、\delta、\sigma。大写希腊字母一般把首字母大写，比如\Gamma、\Delta、\Sigma。

换行符：LaTeX 中一个空行代表换段。如果你想在同一段落内强制换行，使用\\或者\newline；要换段，直接空一行，或者用\par。在正文中不要滥用\\，那通常是表格或对齐环境里用的。

弧符号：表示一段弧AB，我比较习惯用\overset{\frown}{AB}，需要引入amsmath宏包：

\usepackage{amsmath} % 正文中 $\overset{\frown}{AB}$

这些都是很基础的语法，但配合容器化环境，能减少很多“环境导致报错”的干扰，方便我们把注意力放在内容本身。

5.5 常见问题速查表

6. 进阶：用 Compose 固化编译服务

6.1 用 docker-compose 管理编译环境

当你把 LaTeX 编译环境当成一个需要长期维护的基础设施，而不是临时敲命令的工具时，写一份docker-compose.yml会让整个流程更清爽。以后进入项目目录，一条docker compose up就能进入编译环境，或者直接在容器里跑其他脚本。

我的项目根目录里放着这样一个docker-compose.yml：

services: latex: image: my-latex:2025 container_name: latex-build working_dir: /work volumes: - .:/work - ./fonts:/usr/local/share/fonts:ro user: "${UID:-1000}:${GID:-1000}" entrypoint: ["latexmk", "-xelatex", "-interaction=nonstopmode"] command: ["main.tex"]

然后编译论文：

docker compose run --rm latex

这比把一长串docker run参数复制来复制去强得多。Compose 文件本身就是项目文档，别人拿到你的项目，看一眼就知道编译环境怎么搭。这个思路，和你在生产环境用 Compose 编排 Redis 主从、MySQL 这些服务是完全一致的——把环境配置代码化、共享化。

6.2 团队协作与自动构建

容器化之后，团队协作就简单了。你只需要把Dockerfile和docker-compose.yml一起提交到 Git 仓库，其他人第一次克隆项目时执行一次docker build，之后所有编译都用同一个镜像。导师、同学、室友再也不需要各自手动装 TeX Live。

更进一步，可以把编译接入流水线。很多 CI 平台都支持直接运行 Docker 容器，以 GitHub Actions 为例，让服务器拉取你的镜像，执行latexmk -xelatex main.tex，然后把 PDF 作为构建产物打包上传。这样每次 push 都能自动出一份最新 PDF，审阅的人只需要下载产物，不需要配任何 LaTeX 环境。每月省下来的沟通成本，比想象中多很多。

我自己的一个项目组里，大家已经习惯了“只看 CI 出来的 PDF”，本地代码只要保证能通过编译即可。一旦有人改坏格式或者宏包引用，CI 会第一时间在日志里标出来，根本等不到提交合并。

6.3 编译缓存和效率优化

最后说说效率。用容器编译确实比裸机多一点开销，主要是冷启动镜像和文件系统挂载。但对几十页论文来说，编译本身通常只要几秒到十几秒，这部分开销可以接受。

如果你频繁编译同一份大文档，可以考虑给容器指定固定名称，复用同一个容器的缓存：

docker run -d --name latex-daemon -v "$(pwd):/work" -w /work my-latex:2025 tail -f /dev/null docker exec latex-daemon latexmk -xelatex main.tex

用exec进入同一个容器反复编译，能省去每次docker run的启动开销。编译完成后用docker stop latex-daemon停掉即可。这个方法在项目接近完成、需要频繁微调排版格式的阶段特别有用。

最后再说两句

我最初用 Docker 跑 LaTeX，是因为毕业论文改了十几稿，导师给了一份模板，要求所有人统一格式。大家在各自电脑上编译出来的效果始终有细微差异，后来我把编译环境容器化共享出去，格式问题一夜清零。整个过程中感受到最大的收获，不是省了多少磁盘和下载时间，而是“环境确定性”带来的安心感——只要镜像不变，结果永远可控。

最后再分享一个小技巧：写论文时常用的latexmk -pvc模式，在 Docker 里也可以配合使用。它会持续监听源文件变化，自动重新编译更新 PDF。配合 VS Code 的预览，几乎能做到“写一行，看一行”。你只需要保证容器不退出，比如用 6.3 节里的 detached 容器方式，然后：

docker exec latex-daemon latexmk -pvc -xelatex main.tex

不过要提醒一下，latexmk -pvc在前台会一直占用终端，建议用一个单独的终端窗口或者在 VS Code 的任务里跑。等论文交稿的时候，看着那台“编译守护”容器，你会觉得这一路折腾非常值得。