企业官网建设流程全解析

近两年凡是写过毕业论文章节或者投过期刊的人，多少都被 LaTeX 编译环境折磨过。装一个完整的 TeX Live 动辄几个 GB，升级一个宏包可能要全局重来，换一台电脑环境又得从头收拾一遍。更不用说同一份文档在不同机器上编译出来的效果可能完全不一样。我也在这种反复折腾里耗了不少时间，后来决定彻底换个思路：把 TeX Live 装进 Docker 里。这个方案我现在用了很长时间，实际体验稳定、干净，还能和 VS Code 无缝配合，顺着模板改改就能出 PDF。这篇内容就把我搭建这套 LaTeX 编译平台的完整过程、踩过的坑和优化细节一次性讲清楚。

Docker 部署 TeX Live：轻松搭建 LaTeX 论文排版编译平台

1. 为什么用 Docker 装 LaTeX：本地安装的坑有多深

1.1 本地安装的典型痛点

先聊聊本地安装 TeX Live 到底哪里让人抓狂。

第一是体积和安装时间。完整的 TeX Live 套装接近 4 GB，即便只装 scheme-small 或 scheme-medium，也动不动就是几百 MB 起步。网络稍微不稳，下载过程直接劝退。安装完毕后系统里多出一堆二进制文件、字体、宏包，想卸载还不一定能清理干净。

第二是版本管理混乱。写作时经常遇到这种情况：A 论文用到了某个宏包的新特性，B 模板却因为宏包版本太新而编译报错。如果只有一个全局 TeX Live，就只能反复升级或者降级宏包，一来二去系统环境就被改乱了。

第三是跨平台和跨机器的行为不一致。同一份文档在 Windows 上编译没问题，到了 macOS 上字体路径不同、行距略有差异，最终 PDF 的排版细节对不上，投稿时就容易出问题。

我自己还碰到过一个很典型的问题：系统里之前装过某个旧版 CTeX 宏集，结果新版 TeX Live 装好之后，编译中文文档时突然报出找不到字体文件的错误。后来排查了很久才发现是旧版本的字体路径污染了新版环境。

1.2 Docker 方案的核心优势

Docker 的思路本质上把“编译环境”变成了一种可打包、可迁移的资产。我本地不装任何 TeX 工具链，只装一个 Docker，所有编译能力都在容器里完成。

这样做的好处非常具体：

• 环境隔离。容器里的 TeX Live 和宿主机完全独立。容器里怎么装宏包、怎么改配置，都不会影响宿主机。
• 一致性。同一个镜像在任何机器上表现一致，避免了“我这能编你那不行”的问题。
• 可复用。一个镜像可以在多台机器上重复使用，也可以打包分享给团队。
• 易清理。不用的时候删掉容器和镜像即可，宿主机不会留下任何残留。

从使用角度，Docker 把 LaTeX 编译变成了一座标准化的“工厂流水线”。我不需要关心流水线内部是什么操作系统、装了什么宏包，只要把 LaTeX 源文件作为原料放进去，就能稳定产出 PDF 成品。

1.3 哪些人最适合用这套方案

根据我的使用体验，下面几类用户从这套方案里获益最大。

1. 论文写作频繁、但不想维护本地 TeX Live 的学生和科研工作者。
2. 需要在多台设备间切换写作场景的远程工作人群。
3. 需要保证多人协作时编译结果一致的实验室或团队。
4. 对 LaTeX 了解不深、希望开箱即用的小白用户。

说实话，如果你只是偶尔编一份简历或者简单的 PDF，完全没必要上 Docker。但只要是高频使用 LaTeX、或者对环境一致性有要求的场景，这个方案就值得投入半小时搭建。

2. 部署前的准备与镜像选型

2.1 基础环境要求

开始之前先确认本机 Docker 环境就绪。

• Windows：安装 Docker Desktop 后，确认 WSL 2 后端已经启用。
• macOS：Docker Desktop 直接安装即可，Apple Silicon 芯片建议选择 arm64 版本镜像。
• Linux：安装 Docker Engine 和 docker compose 插件即可，无需桌面版。

验证 Docker 是否正常运行，在终端执行：

docker version

如果能看到 Client 和 Server 两部分的版本信息，说明 Docker 已经在运行了。再确认一下 compose 插件：

docker compose version

这一版信息正常输出，就说明环境准备完毕。

注意：Windows 上 Docker Desktop 依赖 WSL 2 和虚拟化支持。如果启动报错，先到 BIOS 里确认虚拟化技术已经开启，再在“启用或关闭 Windows 功能”里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。

2.2 镜像选型对比

Docker Hub 上常见的 TeX Live 镜像主要有以下几类，我列个表方便对比参考：

这里细说一下 texlive/texlive 镜像。它的历史版本标签命名规则很清晰，比如 texlive/texlive:latest 默认指向最新稳定版，texlive/texlive:2025 则固定到某个具体年份版本。如果你希望编译行为和本地某个特定 TeX Live 版本保持一致，那就用具体年份的标签。

snowdreamtech/texlive 则在开箱易用性上更胜一筹，内置了一大批常用宏包，尤其对中文字体和 CTeX 宏集支持友好。如果主要写中文论文，不想折腾字体和宏包缺失问题，直接用这个镜像更省心。

2.3 为什么我选择 texlive/texlive 作为主力镜像

我最终选的是 texlive/texlive:latest 作为主力镜像。原因是这个镜像背后有官方维护团队，tag 更新及时、宏包覆盖面广、兼容性有保障。

搭配方案是：日常使用 texlive/texlive:latest 编译英文文档和通用模板，当碰到中文论文场景时，如果需要更多中文字体和符号支持，再切到 snowdreamtech/texlive 镜像。两个镜像同时存在并不冲突，因为容器本身天然隔离，互不干扰。

需要说明的是，texlive/texlive 这个镜像体型比较大，首次拉取可能要等几个小时。这里有个技巧：如果你后续要跑 CI/CD 流水线，建议直接使用具体的年份 tag（比如 texlive/texlive:2025），避免每次构建时的“latest”发生变化导致编译结果不一致。

3. 完整部署流程：从拉取镜像到编译出第一个 PDF

3.1 拉取官方镜像

打开终端，先拉取镜像：

docker pull texlive/texlive:latest

这里有个小建议：如果你带宽有限，尽量选在大流量时段下载。镜像解压以后大概占 8 GB 左右，加上 Docker 本身的系统盘占用，尽量保留至少 20 GB 空闲磁盘。

拉取完成后验证镜像是否可用：

docker images | grep texlive

如果能看到 REPOSITORY 为 texlive/texlive 的记录，说明镜像已经就位。

3.2 建立工作目录与挂载方式

Docker 容器内是独立文件系统，需要把宿主机上的论文目录挂载进去，容器才能访问源文件。我的习惯是建立一个固定工作目录，比如~/latex-projects，下面按论文或项目分子目录存放。

在宿主机创建目录并写一个最简单的测试文件：

mkdir -p ~/latex-projects/hello cd ~/latex-projects/hello

新建一个 hello.tex，内容如下：

\documentclass{article} \begin{document} Hello, Docker + LaTeX! \end{document}

接下来用 docker run 启动容器并挂载目录：

docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest pdflatex hello.tex

这条命令的参数解释一下：

• --rm：容器运行完自动删除，不留垃圾。
• -v $(pwd):/workspace：把当前目录挂载到容器内的 /workspace。
• -w /workspace：进入容器后默认工作目录切换为 /workspace。
• 最后一个参数是容器内要执行的编译命令。

如果一切正常，你会在当前目录下看到 hello.pdf 生成。至此，Docker 版 LaTeX 编译环境已经跑通。

3.3 常用编译命令的容器内写法

实际论文写作时，编译命令远不止 pdflatex 一个。我在这里把常用命令的应用场景和容器内写法统一整理一下。

对于英文小文档，直接使用：

docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest pdflatex main.tex

对于包含参考文献的论文，需要明确调用 BibTeX，命令序列如下：

docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest pdflatex main.tex docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest bibtex main docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest pdflatex main.tex docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest pdflatex main.tex

这里解释一下为什么要执行多遍 pdflatex。LaTeX 的交叉引用和文献引用机制需要运行多轮才能稳定：第一遍记录引用信息，后续轮次再根据记录回填编号。中文用户最常遇到的情况是 \cite 标注在首次编译后显示成问号，其实第二次编译就恢复了。

使用 latexmk 自动化管理多轮编译是一种更省心的方式：

docker run --rm -v $(pwd):/workspace -w /workspace texlive/texlive:latest latexmk -xelatex main.tex

这里特意用了-xelatex，因为如果你写中文论文，XeLaTeX 配合 CTeX 宏包是目前兼容性最好的编译方案。它把 Unicode 和字体系统完美融合，避免了传统 pdflatex 在字体编码处理上的各种限制。

3.4 中文论文排版的关键配置

中文论文是 LaTeX 使用的重头戏，这里单列一节重点说明。

第一，务必使用 XeLaTeX 编译。传统 pdflatex 需要额外的 CJK 宏包和繁琐的字体配置，而 XeLaTeX 可以直接调用系统字体，处理中日韩文字更自然。

第二，文档导言区引入 ctex 宏包：

\documentclass[UTF8]{ctexart} \begin{document} 中文排版测试。 \end{document}

ctexart 是 CTeX 宏集提供的文档类，专门面向中文论文和报告，排版效果最接近国内学位论文规范。

第三，中文字体的选择。使用 ctex 宏包时，通过 fontset 选项可以指定使用的系统字体版本。如果你的论文模板指定了宋体/黑体/楷体，可以通过：

\documentclass[UTF8, fontset=windows]{ctexart}

这里的 fontset 参数可选 windows、mac、fandol 等。其中 fandol 字体集是 TeX Live 自带的开源中文字体，如果你用的是 Docker 镜像，不依赖宿主机安装任何中文字体，推荐直接用 fontset=fandol，这样在隔离环境里也能稳定编译出中文文档。

我实测过 texlive/texlive 镜像自带的 fandol 字体已经可以完整支持中文论文的宋体、黑体、楷体和仿宋。这意味着你不需要在宿主机上额外安装中文字体，这也是使用 Docker 编译中文论文的一个巨大便利。

4. 集成到日常写作：VS Code 联动方案

4.1 为什么推荐 VS Code 作为前端编辑器

命令行的方式适合验证环境和脚本自动化，但平时写作还是需要一个好用的编辑器。VS Code 的 LaTeX Workshop 插件是目前体验最好的免费方案，原因有三：

1. 支持语法高亮、自动补全、公式预览。
2. 内置 PDF 预览，保存后自动编译刷新。
3. 可以自定义编译方式，把 Docker 命令作为编译工具链接入。

经过实际体验，把 Docker 作为 LaTeX Workshop 的后端编译工具，和本地 TeX Live 的体验差距几乎为 0。VS Code 只是触发命令，真正干活的是容器。

4.2 latex-workshop 配置 Docker 编译任务

安装好 LaTeX Workshop 插件后，需要在 VS Code 的 settings.json 里插入一段自定义配置，让插件调用 Docker 命令而非本地命令。

在用户设置或工作区设置中添加如下配置：

{ "latex-workshop.latex.recipes": [ { "name": "docker-xelatex", "tools": [ "docker-xelatex" ] }, { "name": "docker-latexmk", "tools": [ "docker-latexmk" ] } ], "latex-workshop.latex.tools": [ { "name": "docker-xelatex", "command": "docker", "args": [ "run", "--rm", "-v", "%DIR%:/workspace", "-w", "/workspace", "texlive/texlive:latest", "xelatex", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%" ] }, { "name": "docker-latexmk", "command": "docker", "args": [ "run", "--rm", "-v", "%DIR%:/workspace", "-w", "/workspace", "texlive/texlive:latest", "latexmk", "-xelatex", "-synctex=1", "-interaction=nonstopmode", "%DOC%" ] } ] }

配置要点说明：

• %DIR%会被 LaTeX Workshop 自动替换为当前源文件所在目录。
• %DOC%会被替换为当前源文件的完整路径。
• -interaction=nonstopmode让编译过程遇到错误不中断等待，方便编辑器捕获日志。
• -synctex=1开启反向定位，方便在 PDF 和源码之间跳转。

配置完成后，打开任意 .tex 文件，点一下编译按钮，VS Code 就会通过 Docker 执行编译。PDF 预览会在编译完成后自动刷新。

我实测下来这套方案非常顺滑。唯一需要注意的是首次编译会慢一点，因为容器每次都是新的一次性启动，后续会好很多。

4.3 使用 Dev Container 打造持久开发环境

如果你希望进入容器做更复杂的操作，比如安装新宏包、修改全局配置，可以使用 Dev Containers 插件。

项目根目录创建.devcontainer/devcontainer.json：

{ "name": "latex-dev", "image": "texlive/texlive:latest", "workspaceFolder": "/workspace", "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind", "customizations": { "vscode": { "extensions": [ "james-yu.latex-workshop" ] } } }

然后在 VS Code 中按 F1，选择“Reopen in Container”，VS Code 就会重新启动一个带 LaTeX 环境的完整开发容器。这时候你在容器内打开终端执行 tlmgr install 某些缺失宏包，效果和直接在容器环境内操作是一样的。

这个模式对团队协作尤其友好，所有人都用同一套环境和配置，妈妈再也不担心“我这编不过你那能编”的老难题了。

5. 实际运行中的常见问题与排查实录

5.1 问题汇总速查表

下面这个表格是我在实际使用中常遇到的问题和对应的解决办法。遇到问题时先看这一节，基本能解决 80% 的情况。

5.2 典型案例深度分析

案例一：运行时提示“virtualization support not detected”。这个问题常见于 Windows 下 Docker Desktop 启动失败，本质是宿主机没有开启硬件虚拟化支持。解决办法是重启进入 BIOS，在 CPU 配置中开启 Intel VT-x 或 AMD-V，然后在 Windows 功能中确认“虚拟机平台”和“适用于 Linux 的 Windows 子系统”均已勾选。开启后重启电脑，Docker Desktop 就能正常启动。

案例二：编译时报错“Package ctex Error: CTeX fontsetfandol' is unavailable”。这个错误出现在某些修改过的 ctex 版本中。最常见的原因是镜像内的字体缓存没有刷新，或者是宏包版本冲突。解决方法是清理辅助文件后重新编译，或者在文档开头显式声明\usepackage[fontset=fandol]{ctex}`。如果仍然报错，把编译命令改成 xelatex 再试一次。

案例三：BibTeX 版本报错，出现类似 “This is BibTeX, Version 0.99d (TeX Live 2022)” 的信息后终止。很多情况下问题不在 BibTeX 本身，而是 .bib 文件里混入了不规范的条目，或者临时文件里有残留的 .bbl 文件。处理办法是删除 .aux、.bbl、.blg 等临时文件，重新执行 latexmk 完整编译流程。实际动手排错过程中，这类报错有几次就是清理后就好了。

案例四：容器内找不到某个字体，编译出来的文档报 “font not found”。这种情况最容易出现在中文排版中，解决思路有两种，一是直接在容器内使用 tlmgr 安装字体相关宏包和字体文件，二是干脆切换到 snowdreamtech/texlive 这种内置更多字体的镜像。考虑到便利性，我自己更习惯于直接用 fandol 字体方案，它不需要宿主机额外安装任何字体。

5.3 我一直在用的避坑小技巧

这里分享几个我实际踩过坑之后总结出来的经验，属于网上教程很少提及的细节。

第一，不要每次编译都手动敲一长串 docker run 命令。把常用命令写进项目的 Makefile，再配合 VS Code 插件触发，效率能提升好几倍。

第二，在项目根目录放一个.dockerignore文件。虽然我们不直接构建镜像，但 Docker 在上下文中扫描整个目录时，加上这个文件可以避免把大量临时文件拷入上下文，提升挂载性能。

第三，如果需要新增宏包，不要直接修改基础镜像。正确做法是在容器内使用 tlmgr 安装完之后，用 docker commit 或编写 Dockerfile 构建一个新镜像，以后所有项目都基于新镜像编译。

第四，区分“编译环境”和“写作环境”。Docker 只管编译，写作和代码跳转交给编辑器。刚开始接触时容易把两件事混在一起，实际两者职责单一才是效率最大化的关键。

6. 进阶思路：定制镜像与流水线化

6.1 用 Dockerfile 定制个人编译镜像

默认的 texlive/texlive 镜像已经非常完善，但你可能需要一些它没内置的宏包或设置。这时就该定制自己的镜像了。

新建一个 Dockerfile：

FROM texlive/texlive:latest # 安装额外宏包 RUN tlmgr update --self \ && tlmgr install algorithm2e \ && tlmgr install enumitem \ && tlmgr install fontawesome5 # 设置默认工作目录 WORKDIR /workspace

然后在同目录执行构建：

docker build -t my-latex:latest .

构建后，自定义镜像 my-latex 就可以替代官方的 texlive/texlive 使用了。这种定制化的思路非常适合固定投稿期刊或毕业论文的团队，把所有需要的宏包一次集成到镜像里，后续编译统一走这个镜像，彻底告别“本地宏包不全”的痛点。

6.2 在 CI/CD 流水线中使用 Docker 编译 LaTeX

结合 Docker 的一键编译能力，还能把论文的编译过程集成到自动化流水线中。举个例子，在 GitHub Actions 里写一个简单的 workflow 文件：

name: Build LaTeX Paper on: push: paths: - 'paper/**' jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Compile LaTeX paper uses: docker://texlive/texlive:latest with: args: | cd paper latexmk -xelatex main.tex - name: Upload PDF uses: actions/upload-artifact@v4 with: name: paper-pdf path: paper/main.pdf

配置好了以后，每次把 .tex 源文件推送到仓库，云端的流水线就会自动编译出新版 PDF。对多人合作的论文项目来说，这个流程等于给文档加了一个“持续发布通道”，每次改动后大家拿到的永远是当期最新的编译成品。

6.3 对自己更高效的脚本化封装

为了更进一步压缩编译成本，我把常用命令封装成了一个小脚本。在宿主机某个目录下创建一个texbuild.sh：

#!/bin/bash set -e IMAGE=${IMAGE:-texlive/texlive:latest} ENGINE=${ENGINE:-xelatex} if [ -z "$1" ]; then echo "Usage: ./texbuild.sh main.tex" exit 1 fi DIR=$(cd "$(dirname "$1")" && pwd) FILE=$(basename "$1") docker run --rm \ -v "$DIR":/workspace \ -w /workspace \ "$IMAGE" \ latexmk -"$ENGINE" -synctex=1 -interaction=nonstopmode "$FILE" echo "Build completed."

之后只需在项目目录下执行：

./texbuild.sh main.tex

脚本会自动识别路径、启动容器、编译输出 PDF。这套脚本我用了很长时间，配合 VS Code 的 latex-workshop，几乎可以完全替代本地 TeX 工具链的使用体验。

我个人在实际操作中最大的体会是，Docker 化 LaTeX 真正解决了“环境焦虑”的问题。以前换电脑、换系统、更新宏包都要提心吊胆，现在只要 Docker 在、镜像在，任何机器上都能以完全一致的方式产出 PDF。如果你也常年在论文排版、期刊投稿里摸爬滚打，非常建议花上一个小时把这套环境搭起来，后面的省心程度会超出你的预期。

最后再提一个很多人忽略的点：镜像不是越新越好，建议固定到一个经过验证的 tag 长期使用。我自己的主力镜像固定在某个稳定版本，只有确定新宏包版本不影响现有文档时才会重新构建。这种谨慎的做法，反而让排版成果更持久可靠。