sergiud/texlive

TeXLive 2020 + make Docker镜像文档

镜像概述

本镜像基于TeX Live 2020版本构建，集成GNU make工具，提供完整的LaTeX文档编译环境与自动化构建能力。旨在解决LaTeX环境配置复杂、版本依赖冲突等问题，适用于本地开发、CI/CD流程集成等场景，无需在宿主环境手动安装TeX Live及相关工具链。

核心功能和特性

• 完整TeX Live 2020环境：包含latex、pdflatex、xelatex、lualatex等编译工具，以及常用宏包（如amsmath、graphicx、hyperref等）。
• 集成GNU make工具：支持通过Makefile定义多步骤编译流程（如交叉引用处理、 bibliography生成、多文件合并等），实现自动化构建。
• 文件系统灵活挂载：支持将宿主目录挂载至容器工作目录，便于本地文档编辑与编译结果实时同步。
• 环境一致性保障：统一的编译环境，避免因宿主TeX版本、宏包差异导致的文档编译错误。

使用场景和适用范围

• 学术文档编译：学术论文、学位论文、期刊文章等LaTeX格式文档的本地编译与预览。
• 技术文档自动化：通过Makefile定义技术手册、API文档的编译规则，实现"一键构建"。
• CI/CD流程集成：作为持续集成环节的一部分，自动编译文档并输出PDF（如GitHub Actions、GitLab CI）。
• 多环境隔离：在不干扰宿主系统的前提下，快速切换LaTeX编译环境（本镜像固定为TeX Live 2020，适合版本锁定需求）。

使用方法和配置说明

基础使用（docker run）

通过docker run命令启动容器，挂载本地文档目录至容器内工作目录（默认推荐/workspace），执行编译命令。

编译单个LaTeX文件

bash
# 挂载当前目录（含document.tex）至容器/workspace，执行pdflatex编译
docker run --rm -v $(pwd):/workspace texlive2020-make pdflatex document.tex

• --rm：容器退出后自动删除，避免残留容器。
• -v $(pwd):/workspace：将宿主当前目录挂载至容器/workspace，编译结果（如document.pdf）会保存在宿主当前目录。

使用Makefile自动化编译

若文档编译涉及多步骤（如pdflatex→bibtex→pdflatex×2），可通过Makefile定义流程，在容器内执行make命令。

1. 本地创建Makefile（示例）：

makefile
# Makefile内容
PDF = document.pdf
TEX = document.tex

all: $(PDF)

$(PDF): $(TEX)
    pdflatex $(TEX)
    bibtex $(basename $(TEX))
    pdflatex $(TEX)
    pdflatex $(TEX)

clean:
    rm -f *.aux *.log *.out *.bbl *.blg $(PDF)

2. 容器内执行make：

bash
# 挂载当前目录（含Makefile和document.tex），执行make
docker run --rm -v $(pwd):/workspace texlive2020-make make

• 执行make clean可清理编译中间文件：

  bash
  docker run --rm -v $(pwd):/workspace texlive2020-make make clean
  

交互模式（进入容器终端）

如需在容器内进行多步操作（如调试编译错误），可启动交互式终端：

bash
docker run -it --rm -v $(pwd):/workspace texlive2020-make /bin/bash

进入容器后，工作目录默认切换至/workspace，可直接执行pdflatex、make等命令。

目录挂载与权限说明

• 挂载路径：推荐固定使用/workspace作为容器内工作目录，避免路径混乱。
• 权限问题：若宿主目录权限严格（如Linux系统），可能出现"权限拒绝"错误，可通过--user参数指定用户ID（与宿主当前用户ID一致）：

  bash
  # 获取宿主当前用户ID（通常为1000）
  echo $UID
  # 以指定用户ID启动容器，解决权限问题
  docker run --rm -v $(pwd):/workspace --user $(id -u):$(id -g) texlive2020-make pdflatex document.tex
  

Docker部署方案示例

docker-compose配置示例

适用于需要长期维护的文档项目，通过docker-compose.yml简化命令。

yaml
# docker-compose.yml
version: '3'
services:
  texlive:
    image: texlive2020-make
    volumes:
      - ./docs:/workspace  # 挂载宿主./docs目录至容器/workspace
    command: make  # 默认执行make命令（可替换为具体编译命令）

启动服务：

bash
docker-compose up

注意事项

1. TeX Live版本锁定：本镜像基于TeX Live 2020，不支持宏包在线更新（如需更新宏包，需手动在容器内执行tlmgr update，但建议优先使用镜像内置版本以保证一致性）。
2. 中文字符支持：默认已包含ctex宏包，可通过xelatex或lualatex编译中文文档（需在.tex文件中配置中文字体）。
3. 大型项目编译：若文档包含大量图片或复杂宏包，建议增加容器内存限制（如--memory=2g），避免编译过程中内存不足。