> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/texlive/zh-cn/zai-docker-zhong-shi-yong-texlive.md).
# 在 Docker 中使用 TeXLive
### Docker
Docker 提供了一种轻量且可移植的方式，用于在隔离的容器中打包和运行应用程序。通过将应用程序与其所需的所有依赖一起捆绑，容器能够确保从笔记本电脑到生产服务器等不同机器上的行为一致。
TeX Live 功能强大，但体积庞大，并且对系统级差异较为敏感。将 TeX Live 打包进 Docker 镜像中，可以让 LaTeX 工具链变得可预测、可复现且易于分发。
不过，一些 TeX Live 包依赖 shell 访问。出于安全原因，容器应运行在受限环境中，以防止用户执行任意 shell 命令（例如通过 `\write18` 或 shell escape）。这种隔离可以保护主机系统，并避免对容器底层文件系统或诸如 `bash`.
### TeXLive 完整版
[TeXLive-Full@ayaka-notes](https://github.com/ayaka-notes/texlive-full/) 是一个功能完整的 **TeXLive Docker 镜像** 专为 Overleaf Server Pro、Overleaf Pro 以及独立的 LaTeX 编译环境（如 CI 或流水线）而设计。
该镜像旨在提供一个几乎完整的 TeXLive 发行版，并预装常用字体和工具，以尽量减少因缺少包或字体导致的编译失败。
特性：
* 🚀 同时支持 x86\_64 和 arm64 服务器架构
* 📦 完整且优化过的 TeXLive 安装
* 🧩 预装常用字体和实用工具
* 🐳 可直接与 Docker 和 Docker Compose 一起使用
* 🧪 已在 Overleaf Server Pro / Overleaf Pro 上测试
* 🔄 定期更新到最新的 TeXLive 版本
* 🏷 多个 TeXLive 版本标签（2020 – 最新）
* 🧑🔬 支持在 LaTeX 文档中使用 R 代码的 Knitr
### Overleaf Pro 使用方法
[TeXLive-Full@ayaka-notes](https://github.com/ayaka-notes/texlive-full/) 支持 **overleaf pro**，你可以使用以下环境变量来 `config/variables.env` 文件，如果你是 [toolkit 用户](https://github.com/overleaf/toolkit).
例如：
{% code title="config/variables.env" overflow="wrap" %}
```dotenv
ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1
```
{% endcode %}
### TeXLive 版本
得益于 Github Action，我们可以并行构建所有 tex 镜像，其中包括：
* `ghcr.io/ayaka-notes/texlive-full:2026.1` （也有 `latest` 标签）
* `ghcr.io/ayaka-notes/texlive-full:2025.1`
* `ghcr.io/ayaka-notes/texlive-full:2024.1`
* `ghcr.io/ayaka-notes/texlive-full:2023.1`
* `ghcr.io/ayaka-notes/texlive-full:2022.1`
* `ghcr.io/ayaka-notes/texlive-full:2021.1`
* `ghcr.io/ayaka-notes/texlive-full:2020.1`
* `ghcr.io/ayaka-notes/texlive-full:base`
我们使用来自 [texlive info](https://texlive.info/tlnet-archive/)的镜像归档，其中几乎包含了从 1996 到 2026 的所有 texlive 镜像。并且多亏了 Overleaf 的 Dockerfile，我们可以更快地构建这个项目。
> 为什么不支持 texlive 2019 及更早版本？
>
> 维护这类镜像非常困难。而且我们认为你可能已经不会再使用它了，因为它太旧了。如果你需要，请提一个 issue 告诉我。
### 包含的组件
以下包已包含在 docker 镜像中。
* 所有 TeXLive 包（该年份的）
* R 包（仅选定的）
* fontconfig inkscape pandoc python3-pygments wget python3
* gnupg gnuplot perl-modules perl ca-certificates
* ghostscript qpdf r-base-core tar
以下字体已包含在 docker 镜像中。
* [Google Fonts](https://fonts.google.com/)
* [Microsoft msttcorefonts](https://packages.ubuntu.com/jammy/ttf-mscorefonts-installer)
* [Overleaf 支持的字体](https://www.overleaf.com/learn/latex/Questions/Which_OTF_or_TTF_fonts_are_supported_via_fontspec%3F)
{% hint style="warning" %}
请确认相关字体是否可以商用。我们对 **不承担责任** 因你对字体的错误使用而引发的任何法律问题。下载镜像后，即表示你自动同意这一点。
{% endhint %}
### 许可证
MIT
### 问题
问题 01：字体缓存缺失问题
当 overleaf 编译 latex 项目时，如果发生字体缺失， **你可能会发现编译过程耗时很长**，这是因为当字体缺失时，texlive 会尝试 **重建整个字体缓存**。这是一个耗时的过程。
在我们的镜像中，我们已经预先构建了字体缓存，我们通过 [这个提交](https://github.com/ayaka-notes/texlive-full/commit/0cb66b0dc8b82be628cf6999cfd659d9784e132f)
问题 02：Sync Tex 极其缓慢
当你在 sharelatex 中使用这个镜像时，你可能会发现 sync tex 非常慢。
参见： ，只需禁用 http 2.0。
问题 03：使用官方 Texlive 镜像重新编译时出错
如果你使用 docker hub 上的 texlive 官方镜像 `texlive/texlive`，你可能会发现当你重新编译项目时会报错。不过在我们的镜像中，这个问题已被修复。因为我们使用了最新的 ubuntu 基础镜像，并从 ubuntu 官方仓库安装了所有依赖。
### 其他技术提醒
在构建 texlive 镜像（2019 年之前）时，你可能需要注意以下问题：
* 仅 `http`/`ftp` 在 texlive 2017 之前被支持，所以你不能使用 `https` 下载，除非你修改 `peal` 脚本。
* 2015 年之前，只提供 sha256 文件。因此你不能使用 sha512 来校验。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://ayakaleaf-pro.ayaka.space/texlive/zh-cn/zai-docker-zhong-shi-yong-texlive.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.