如何强制gitlab-runner exec docker使用本地镜像？

云上老周

2026-5-19

强制GitLab Runner Exec Docker使用本地镜像的方法

我之前也被这个问题坑过，分享几个亲测有效的方法，帮你搞定：

确保镜像标签完全匹配
首先要保证你本地构建的镜像，和.gitlab-ci.yml里image字段指定的镜像名称、标签完全一致。比如你本地有my-custom-image:dev，那ci文件里必须写image: my-custom-image:dev，不能只写my-custom-image（默认会拉取latest标签），否则Runner还是会尝试去远程仓库拉取。
使用命令行参数指定拉取策略
直接在执行命令时加上--pull-policy参数，这是最快捷的临时解决方案：
- 如果你确定本地一定有目标镜像，用never策略，完全禁止拉取远程镜像：
```
gitlab-runner exec docker --pull-policy never <你的Job名称>
```
- 如果你想让Runner只在本地没有镜像时才去拉取，用if-not-present策略：
```
gitlab-runner exec docker --pull-policy if-not-present <你的Job名称>
```
修改Runner配置文件设置默认拉取策略
如果你不想每次执行命令都加参数，可以修改GitLab Runner的配置文件（通常路径是/etc/gitlab-runner/config.toml），在对应Runner的[runners.docker]区块下添加拉取策略：
```
[[runners]]
  name = "你的Docker Runner名称"
  executor = "docker"
  [runners.docker]
    image = "默认镜像名称"
    pull_policy = "never"  # 或者 "if-not-present"
    # 其他配置项...
```
修改完成后，重启GitLab Runner服务使配置生效：
```
gitlab-runner restart
```
排查本地镜像是否存在
最后可以先确认本地确实有目标镜像，执行docker images命令查看，确保镜像名称、标签和ci文件里的完全对应，避免因为拼写错误导致Runner去拉取远程镜像。