GitLab CI自动编译LaTeX时无法找到图片的问题咨询

问题描述 #

在GitLab CI中自动编译LaTeX生成PDF时，pdflatex无法找到引用的图片，报错如下：

! Unable to load picture or PDF file 'graphics/.../image.png'.
<to be read again> 

Latexmk: Missing input file: 'graphics/.../image.png' from line
'LaTeX Warning: File `graphics/.../image.png' not found on input line 802.'

当前使用的.gitlab-ci.yml配置：

stages:          # List of stages for jobs, and their order of execution
  - compile

compile_pdf:
  stage: compile
  image: tianon/latex
  script:
    - latexmk -pdf -pdflatex="xelatex -interaction=nonstopmode" -use-make thing.tex
  artifacts:
    paths:
      - thing.pdf

Makefile内容：

# You want latexmk to *always* run, because make does not have all the info.
# Also, include non-file targets in .PHONY so they are run regardless of any
# file of the given name existing.
.PHONY: thing.pdf all clean

# The first rule in a Makefile is the one executed by default "make". It
# should always be the "all" rule, so that "make" and "make all" are identical.
all: thing.pdf

# CUSTOM BUILD RULES

# In case you didn't know, '$@' is a variable holding the name of the target,
# and '$<' is a variable holding the (first) dependency of a rule.
# "raw2tex" and "dat2tex" are just placeholders for whatever custom steps
# you might have.

# %.tex: %.dat
#         ./dat2tex $< > $@

# MAIN LATEXMK RULE

# -pdf tells latexmk to generate PDF directly (instead of DVI).
# -pdflatex="" tells latexmk to call a specific backend with specific options.
# -use-make tells latexmk to call make for generating missing files.

# -interaction=nonstopmode keeps the pdflatex backend from stopping at a
# missing file reference and interactively asking you for an alternative.

thing.pdf: thing.tex
    latexmk -pdf -pdflatex="xelatex -interaction=nonstopmode" -use-make --shell-escape thing.tex

clean:
    latexmk -CA

解决方案 #

• 验证仓库中图片的存在性与路径正确性

  1. 确认LaTeX代码中引用的graphics/.../image.png路径，与Git仓库中的实际文件路径完全一致（Linux环境大小写敏感，注意文件名和目录名的大小写）。
  2. 检查.gitignore文件，确保图片文件或graphics目录没有被排除，且图片已经提交到仓库中。

• 检查CI编译的工作目录
  如果TeX文件不在仓库根目录，需确保编译命令的工作目录与TeX文件所在目录匹配。可以在CI脚本中先切换目录再执行编译：

  script:
    - cd path/to/tex/files
    - latexmk -pdf -pdflatex="xelatex -interaction=nonstopmode" -use-make thing.tex
  

• 暂时简化编译流程排查问题
  先移除Makefile的依赖，直接在CI脚本中执行编译命令，确认是否是Makefile规则导致路径问题：

  script:
    - latexmk -pdf -pdflatex="xelatex -interaction=nonstopmode" thing.tex
  

  如果此方式能成功编译，再逐步排查Makefile中的配置（比如--shell-escape是否必要，或者是否存在路径覆盖的情况）。

• 确认CI环境中文件可访问
  可以在CI脚本中添加文件检查命令，验证图片在编译环境中是否存在：

  script:
    - ls -l graphics/.../
    - latexmk -pdf -pdflatex="xelatex -interaction=nonstopmode" -use-make thing.tex
  

内容的提问来源于stack exchange，提问作者KalvinB