| name | latex-compiling |
| description | 当需要用系统级 latexmk 和 pdflatex 编译 LaTeX,并把 PDF、中间文件、TeX 缓存与源码目录隔离时使用。 |
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。
- 参考文献、目录、交叉引用、图片、表格、公式和中文字体是否正常。