为什么GitLab CI部署作业无法找到已缓存的documentation文件夹？

问题根因 #

1. 缓存未上传到共享存储（最核心原因） #

从文档生成作业的日志可以看到明确警告：No URL provided, cache will be not uploaded to shared cache server. Cache will be stored only locally.，说明你使用的GitLab Runner未配置共享缓存后端，生成的缓存仅存储在当前作业运行的Runner节点本地。如果部署作业被调度到其他Runner节点执行，自然无法拉取到仅存在于前一个节点本地的缓存文件。

2. GitLab版本不支持多缓存配置 #

你部署作业的缓存采用了数组形式的多缓存配置，该特性仅在GitLab 13.10及以上版本支持。如果你的GitLab实例版本低于要求，部署作业的缓存配置会直接失效，不会拉取任何缓存内容。

3. 路径匹配或工作目录不一致 #

虽然缓存日志显示frontend/documentation路径下找到匹配文件，但如果两个作业的执行工作目录不同，也可能导致部署作业无法找到对应路径的文件。

解决方案 #

• 优先修改GitLab Runner的config.toml配置，补全[runners.cache]段的共享缓存配置（可选择S3、MinIO、本地共享目录等作为缓存后端），确保所有Runner节点都可以访问到上传的缓存文件。
• 检查GitLab实例版本，若低于13.10，将部署作业的多缓存配置合并为单缓存条目，或升级GitLab到支持该特性的版本。
• 可在部署作业的script段最开头添加ls -la frontend命令，打印当前目录结构，确认是缓存未拉取成功还是路径配置问题。
• 确保两个作业的Runner标签配置一致，优先调度到同一组Runner节点执行，避免跨节点缓存失效问题。

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