首页/云/Docker 容器速查/docker run --pull 拉取策略
基础命令50 条

docker run --pull 拉取策略

控制 run 之前是否联网拉取镜像:missing 用本地优先,always 强制更新 tag,never 只允许使用本地已有镜像(离线环境)。

Docker 容器速查云更新于 2026-10-13

--pull 拉取策略是什么

--pull 控制 docker run 之前的镜像拉取行为:missing 只在本地没有时拉取、always 每次运行前检查更新、never 只用本地镜像。默认是 missing,因此在 CI 里很容易悄悄用上构建机上的旧镜像。

基本信息

用途控制运行前的镜像拉取时机
语法--pull=always|missing|never
默认值missing,本地有同名镜像就不联网
离线环境用 never,仅使用本地已有镜像
可重现性固定版本标签,或直接按摘要引用

典型使用场景

  • CI 部署固定标签的镜像:用 always 确保拿到仓库最新推送的同一标签
  • 离线与气隙环境启动容器:用 never 避免因无网络而失败
  • 排查“镜像更新了但容器行为没变”:确认拉取策略与标签是否真的更新
  • 本地反复调试同一镜像时用 missing,省掉每次访问仓库的开销
  • 发布核对镜像摘要,保证不同机器拿到完全一致的镜像
  • 自动化脚本统一策略,避免不同环境行为不一致

示例

示例
docker run --rm --pull=always nginx:1.27-alpine nginx -v   # 运行前检查更新
docker run --rm --pull=never alpine:3.20 /bin/true           # 只用本地镜像
docker pull nginx:1.27-alpine                                # 也可以先显式拉取
docker image inspect nginx:1.27-alpine -f '{{index .RepoDigests 0}}'   # 核对摘要

三种策略的行为

取值行为适用场景
missing本地没有才拉取(默认值)日常使用,省去网络往返
always运行前检查并更新同名标签CI 部署,确保拿到新推送的同名标签
never绝不联网,只用本地镜像离线与气隙网络环境
按摘要运行不涉及标签解析对可重现性要求最高的场景
always 会覆盖本地同名标签的引用,回滚时不要指望本地还留着旧版本的镜像。
CI 里用 latest 搭配 missing,很容易误用构建机上遗留的缓存镜像,固定标签或摘要才是可靠做法。
内网无出口的环境使用 always 会直接报网络错误,此时应改成 missing,或提前拉取后用 never 启动。

易错点

  • 以为 --pull=always 会拉到“最新版本”:它只更新指定的那个标签,标签本身没变时拉到的仍是同一镜像
  • always 覆盖本地同名标签后需要旧版本时无法回滚,回滚基线要用另一个标签或摘要保留
  • 离线环境误加 always,容器起不来并报网络错误,应改用 never 或先预拉取镜像
  • 只靠标签管理版本:上游重新推送同名标签后,两台机器行为可能不一致,关键发布按摘要固定

数据来源与参考

  • Docker 官方 CLI 参考:docker run --pull(docs.docker.com)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌