DockerTeX 和 DockerTeXstudio 中文技术文档

镜像概述和主要用途

DockerTeX 和 DockerTeXstudio 是一系列提供完整 LaTeX 环境的 Docker 镜像，支持多种 TeX Live 版本和 TeXstudio GUI。这些镜像基于 Debian 和 Ubuntu 构建，旨在为 LaTeX 文档开发提供一致、隔离且功能完备的环境，适用于从命令行编译到 GUI 编辑的各种使用场景。

可用镜像

当 Debian 或 Ubuntu 基础镜像更新时（平均每月一次），所有镜像都会在 Dockerhub 上自动重建。

核心功能和特性

• 多版本支持：提供从 TeX Live 2012 到 2022 的所有版本
• 完整 LaTeX 环境：包含 texlive-full 包，涵盖几乎所有常用 LaTeX 模块
• TeXstudio GUI：所有容器中均可启动 TeXstudio 图形界面编辑器
• 预安装工具：包含 biber、make、gnuplot、inkscape、pandoc、python-pygments 等常用工具
• 文件权限保护：确保容器生成或修改的文件保持原有用户和组所有权
• X 服务器集成：TeXstudio GUI 通过共享套接字直接在本地 X 服务器上运行
• 双向同步：支持 TeXstudio 的"跳转到 PDF"和"跳转到源代码"功能
• 语法检查：集成 LanguageTool 语法检查工具
• 多引擎支持：兼容 Docker 和 Podman 命令行工具

支持的标签和版本

可通过 TeX Live 版本标签（如 texlive2016）或发行版代号（如 stretch）指定所需版本：

注：EOL 表示该发行版已终止支持，不再接收更新，但镜像仍可正常使用。

使用场景和适用范围

1. 学术写作：为论文、报告和学术文档提供一致的 LaTeX 环境
2. 多版本测试：在不同 TeX Live 版本中测试文档兼容性
3. 命令行编译：集成到自动化工作流或脚本中
4. GUI 编辑：通过 TeXstudio 提供图形界面编辑体验
5. 持续集成：在 CI/CD 管道中自动构建 LaTeX 文档
6. 教学环境：快速部署统一的 LaTeX 教学环境
7. 跨平台开发：在不同操作系统上提供一致的 LaTeX 体验

详细使用方法和配置说明

前提条件

• Docker 或 Podman 引擎
• 对于 GUI 功能（TeXstudio）：本地 X 服务器

DockerTeX (命令行使用)

基本语法

bash
dockertex [-t|--tag tagname] command

示例

编译当前目录中的 document.tex：

bash
# 使用默认标签（texlive2021）
dockertex pdftex document.tex

# 指定特定版本
dockertex --tag texlive2018 pdflatex document.tex

# 使用 Makefile
dockertex --tag texlive2019 make all

环境变量配置

设置默认标签，避免每次输入 --tag：

bash
export DOCKERTEX_DEFAULT_TAG="texlive2018"

指定容器引擎（默认为 podman，如果已安装，否则为 docker）：

bash
export DOCKERTEX_ENGINE="docker"

DockerTeXstudio (GUI 使用)

基本语法

bash
dockertexstudio [-t|--tag tagname] [-v|--volume mapping]* [texstudio options]

示例

启动默认版本的 TeXstudio：

bash
dockertexstudio

指定标签和额外卷挂载：

bash
dockertexstudio --tag texlive2019 --volume /media/data/tex:/home/user/tex

直接打开特定文件：

bash
dockertexstudio --tag texlive2021 document.tex

使用 x11docker 运行（增强安全性）

bash
x11docker --network=host --share $HOME raabf/texstudio-versions:texlive2021

配置说明

默认行为

• 当前工作目录自动挂载到容器中
• 保留文件所有权（用户和组 ID）
• 共享本地 X 服务器以运行 GUI 应用
• 网络与主机共享，支持 LanguageTool 等网络服务

自定义配置

设置默认标签：

bash
export DOCKERTEXSTUDIO_DEFAULT_TAG="texlive2020"

指定容器引擎：

bash
export DOCKERTEXSTUDIO_ENGINE="podman"

Docker 部署方案示例

docker run 命令示例

直接使用 docker 命令运行特定版本的 LaTeX：

bash
# 编译单个文件
docker run --rm -v "$PWD":/workdir -u "$(id -u):$(id -g)" raabf/latex-versions:texlive2021 pdflatex document.tex

# 启动交互式 bash
docker run -it --rm -v "$PWD":/workdir -u "$(id -u):$(id -g)" raabf/latex-versions:texlive2021 bash

运行 TeXstudio GUI：

bash
docker run --rm \
  -v "$HOME":/home/user \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY \
  -u "$(id -u):$(id -g)" \
  --network=host \
  raabf/texstudio-versions:texlive2021

docker-compose 配置示例

创建 docker-compose.yml 文件：

yaml
version: '3'

services:
  latex:
    image: raabf/latex-versions:texlive2021
    volumes:
      - ./:/workdir
    user: "${UID}:${GID}"
    command: pdflatex document.tex

  texstudio:
    image: raabf/texstudio-versions:texlive2021
    volumes:
      - "${HOME}:/home/user"
      - "/tmp/.X11-unix:/tmp/.X11-unix"
    environment:
      - DISPLAY
    user: "${UID}:${GID}"
    network_mode: "host"
    command: texstudio

使用方法：

bash
# 编译文档
UID=$(id -u) GID=$(id -g) docker-compose run latex

# 启动 Texstudio
UID=$(id -u) GID=$(id -g) docker-compose run texstudio

安装方法

通过 zsh 插件管理器安装

推荐使用 zsh 插件管理器安装命令行工具，便于自动更新。

zplug 配置

在 ~/.zshrc 中添加：

zsh
zplug raabf/dockertex, \
    from:gitlab, \
    hook-build:"./posthook.sh --menu-tag latest --menu-volume /media/ext/=/home/ext/"

安装多个版本的菜单条目：

zsh
zplug raabf/dockertex, \
    from:gitlab, \
    hook-build:"./posthook.sh --menu-tag latest; ./posthook.sh --menu-tag texlive2018"

通过自动脚本安装

适用于非 zsh 用户：

bash
# 基本安装（当前用户）
curl [***] | bash -s -- --menu-tag latest

# 系统级安装
curl [***] | bash -s -- --system --menu-tag latest

# 安装并添加额外卷挂载
curl [***] | bash -s -- --menu-tag latest --menu-volume "/media/data/tex:/home/user/tex"

# 仅安装命令行工具，不安装 Texstudio
curl [***] | bash -s -- --no-texstudio

查看帮助信息：

bash
curl [***] | bash -s -- --help

手动安装

1. 复制命令行脚本到 PATH 目录：

bash
sudo cp bin/dockertex.sh /usr/local/bin/dockertex
sudo cp bin/dockertexstudio.sh /usr/local/bin/dockertexstudio
sudo chmod a+x /usr/local/bin/dockertex*

2. 安装图标：

bash
sudo cp misc/icons/hicolor/scalable/apps/texstudio.svg /usr/local/share/icons/hicolor/scalable/apps/

3. 创建桌面快捷方式：

bash
sudo cp misc/dockertexstudio.desktop /usr/local/share/applications/dockertexstudio.desktop
sudo tee -a /usr/local/share/applications/dockertexstudio.desktop << EOF
Name=Docker TexStudio (latest)
Exec=/usr/local/bin/dockertexstudio --tag latest %F
Icon=/usr/local/share/icons/hicolor/scalable/apps/texstudio.svg
EOF

持续集成配置

GitLab CI 配置示例

创建 .gitlab-ci.yml 文件：

yaml
stages:
  - build

build_latest:
  image: raabf/latex-versions:latest
  stage: build
  script:
    - pdflatex -interaction=nonstopmode document.tex
    - biber document
    - pdflatex -interaction=nonstopmode document.tex
  artifacts:
    paths:
      - document.pdf
    expire_in: 1 week

test_texlive2018:
  image: raabf/latex-versions:texlive2018
  stage: build
  script:
    - pdflatex -interaction=nonstopmode document.tex
    - biber document
    - pdflatex -interaction=nonstopmode document.tex
  artifacts:
    paths:
      - document.pdf
    expire_in: 1 week

TexStudio 显示问题故障排除

授权错误

当出现以下错误时：

Authorization required, but no authorization protocol specified

在主机上运行：

bash
xhost local:root

DISPLAY 变量问题

如果提示找不到显示，尝试修改 dockertexstudio.sh 中的显示设置：

将 --env='DISPLAY' 替换为 -e DISPLAY=unix$DISPLAY

网络问题

如果遇到网络相关问题，尝试移除 --network=host 参数，但这可能导致 LanguageTool 等网络功能不可用。

使用 x11docker（替代方案）

如果上述方法仍有问题，尝试使用 x11docker：

bash
x11docker --network=host --share $HOME raabf/texstudio-versions:texlive2021

贡献指南

该项目旨在为大多数 LaTeX 项目提供通用环境。如有任何缺失功能或问题，欢迎贡献。项目仓库和问题跟踪见 GitLab 仓库。

许可证

本项目采用 MIT 许可证。