Latex Compiling

LaTeX 编译

核心原则

• 使用系统级 TeX 工具链，不优先使用 conda 安装 TeX。
• 用 latexmk -pdf 自动处理多轮编译、引用和目录。
• 使用独立 build 目录保存 PDF、中间文件、日志和 TeX 缓存。
• 设置 TEXMFVAR 和 TEXMFCONFIG 到可写目录，避免 TeX 首次生成字体缓存时写入 /tmp、只读目录或不可控位置。

安装

Debian/Ubuntu：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y texlive-latex-extra latexmk ghostscript
apt-get clean

如果没有 root 权限，让系统管理员安装，或使用已有系统级 TeX 环境。

检查：

latexmk -version
pdflatex --version
gs --version

推荐目录结构

project/
  latex/
    main.tex
    sections/
    figures/
  latex_build/
    texmf-var/
    texmf-config/

如果项目会和 Overleaf 同步，不要把编译中间文件写进同步目录。

标准编译命令

cd /path/to/project/latex
TEXMFVAR=/path/to/project/latex_build/texmf-var \
TEXMFCONFIG=/path/to/project/latex_build/texmf-config \
latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=../latex_build main.tex

参数要点：

• -interaction=nonstopmode：遇到错误时尽量输出完整日志，不进入交互模式。
• -halt-on-error：遇到致命错误时停止。
• -outdir=../latex_build：把 PDF 和中间文件输出到 build 目录。
• main.tex：替换为实际入口文件名。

清理

清理中间文件但保留 PDF：

latexmk -c -outdir=../latex_build main.tex

清理中间文件和 PDF：

latexmk -C -outdir=../latex_build main.tex

常见问题

• 找不到 .sty：优先安装系统 TeX 包，或确认模板自带 .sty 在 TeX 可搜索位置。
• 字体缓存写入失败：显式设置 TEXMFVAR 和 TEXMFCONFIG 到 build 目录中的可写子目录。
• 源码目录被中间文件污染：使用 -outdir，不要在源码目录裸跑 pdflatex main.tex。

验证

检查：

• latex_build/main.pdf 是否生成。
• 日志中是否有 Fatal error、Emergency stop、Undefined control sequence。
• 参考文献、目录、交叉引用、图片、表格、公式和中文字体是否正常。