CI (GitHub Actions 等)

CI（continuous integration，持续集成）是指服务器 在每次 push 时自动构建 PDF 的机制。即使不在本地编译，你也总能拿到最新输出，并且能尽早发现“在我的环境能跑”的问题。对于 LaTeX，常见选择是 GitHub Actions：它检出仓库，在 TeX Live 环境中编译，并把生成的 PDF 保存为 artifact。

为什么在 CI 中构建

每次 push 时，文档都会在一个 干净、可重现的 TeX Live 环境 中自动构建。好处是：可以及早发现依赖本地设置的错误；文档始终处于已知可编译状态；没有安装 TeX 的合作者和审稿人也能拿到 最新 PDF；需要时还可以作为 release 发布。构建内容写在 .github/workflows/ 下的 workflow 文件（YAML）中。

最小的 GitHub Actions workflow

把下面的 YAML 放到 .github/workflows/build.yml 就能运行：actions/checkout 获取源码，xu-cheng/latex-action 进行编译，actions/upload-artifact 保存 PDF。GitHub Actions 的主版本会随时间推进；此示例使用 2026 年时的主要版本线：checkout v6 和 upload-artifact v7。

# .github/workflows/build.yml
name: Build LaTeX
on: [push]
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

xu-cheng/latex-action 必须指定 root_file，默认使用 pdfLaTeX。要更换引擎，请设置 latexmk_use_xelatex: true 或 latexmk_use_lualatex: true。对于 upLaTeX + dvipdfmx 这类需要更细步骤的 workflow，把 .latexmkrc 提交到仓库，让 action 读取与本地构建相同的配置，可以缩小本地与 CI 的差异。

这个 YAML 是检查“能否生成 PDF”的最小形式。对于论文或合作论文，应同时在 push 和 pull_request 上运行，避免损坏的 PDF 在审阅前混入。Action 的主版本会升级；如果模板要长期使用，要么接受依赖更新 PR，要么每年安排一次对照官方 README 的检查。

TeX Live 环境 — texlive/texlive 镜像

构建需要 TeX Live，而 latex-action 内部已经包含了它。想细致控制环境时（特定 package、日语等），可以直接使用 Island of TeX 提供的 texlive/texlive Docker 镜像。由于 latest 会持续更新，重视可重现性的提交物应固定到带日期的 tag 或 TeX Live 年度 tag，日常检查则使用 latest，这样更好管理。把它指定为 job 的 container:，然后自己运行 latexmk。

jobs:
  build:
    runs-on: ubuntu-latest
    container: texlive/texlive:latest
    steps:
      - uses: actions/checkout@v6
      - run: latexmk -pdf main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

CI 失败时阅读日志

先把 CI 失败分成三类：LaTeX 错误、缺少 package、artifact 路径错误。如果日志中出现 ! LaTeX Error 或 Undefined control sequence，就调试文档本身；如果 File ... not found 表明缺少 TeX Live package，就调整镜像或安装步骤；如果 upload-artifact 报告没有文件，就核对 path: 和实际输出文件名。本地通过但 CI 失败时，要怀疑是否依赖了只存在于本机的字体、图像或生成好的 .bbl 文件。

将 PDF 作为 artifact 或 release

• 由 actions/upload-artifact 保存的 PDF 可以从 workflow run 页面 下载（每次运行单独保存）。
• 如果要发布公开版本，也可以 把 PDF 附加到 GitHub Release（例如由推送 tag 触发）。
• 日语文档建议在 texlive/texlive 容器中用配置为 uplatex + dvipdfmx 的 latexmk 构建。
• 把构建配置（.latexmkrc 等）随仓库一起提交，让本地和 CI 走相同步骤。
• 用于提交的 workflow 中，启用 -halt-on-error 并保留日志，以便追踪警告原因。