在GitLab CI/CD流水线中并行化递归Makefile构建LaTeX文档

核心结论 #

仅在Makefile 1的$(MAKE) -C $@处添加-jN参数不够，需要分两处配置才能实现真正的并行构建。

具体原因与解决方案 #

1. 顶层调用需传递并行参数 #

在GitLab CI/CD Runner执行顶层Makefile时，必须给顶层的make命令加上-jN参数（比如make -j4）。如果只在递归调用的$(MAKE)里加，顶层make仍会串行处理子目录的递归请求，无法触发并行。

2. 递归Makefile需传递并行参数 #

在Makefile 1的递归调用中，要把顶层的并行参数传递下去，而非硬编码-jN。正确写法为：

$(MAKE) -C $@ $(MAKEFLAGS)

$(MAKEFLAGS)会自动继承顶层make的所有参数（包括-jN），让所有中间层和底层的make进程都能并行执行任务。

3. 底层Makefile 2的注意事项 #

确保Makefile 2中的LaTeX构建任务独立无依赖——不同文档的编译任务不能有交叉依赖（比如共享临时文件），否则并行时会出现文件冲突。LaTeX单文档编译本身无法并行，但多文档之间的并行是安全的，只要每个文档的编译流程在自身目录内完成。

4. 之前尝试无效的可能原因 #

• 仅在递归调用里加了-jN，但顶层make命令未添加，导致顶层串行处理子目录
• 递归调用中硬编码了-jN，但底层Makefile存在隐藏的跨目录依赖，make自动降级为串行执行
• GitLab Runner的资源限制（如CPU核数不足），即使添加-jN也无法真正实现并行

验证方法 #

在GitLab CI/CD的执行脚本里，将顶层命令修改为：

make -j$(nproc)

同时把Makefile 1的递归调用改为$(MAKE) -C $@ $(MAKEFLAGS)，之后观察CI日志是否有多个LaTeX编译进程同时启动。

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