DockerPush推送镜像到DockerHub全流程实战-Docker-PHP中文网

docker login 401 错误需用 personal access token 替代密码，username 填用户名非邮箱；push 失败多因 tag 格式错误（须为 username/repo:tag）、权限不足或网络问题；大镜像应优化分层、启用多阶段构建并清理缓存。

dockerpush推送镜像到dockerhub全流程实战

docker login 报 401 Unauthorized，基本是凭据问题，不是网络或 Docker 服务故障。DockerHub 已停用密码直登，必须用 Personal Access Token（PAT）替代密码。

登录 DockerHub 网页 → Settings → Security → New Access Token → 选 Read and write 权限（Push 镜像必需）
执行 docker login 时，Username 填你的 DockerHub 用户名（不是邮箱），Password 粘贴刚生成的 token
别把 token 存在 shell history 里：执行前先运行 set +o history，输完再 set -o history
macOS 上如果用了 Docker Desktop 自带的凭据助手，token 可能被缓存旧凭据覆盖，可临时删掉 ~/Library/Keychains/login.keychain-db 中相关条目（或直接在钥匙串里搜 “docker” 删除）

镜像推送到 DockerHub，必须带完整命名空间，格式是 username/repository:tag。本地构建的镜像默认只有 myapp 这种名字，不加前缀 push 肯定失败。

查看当前镜像 ID：docker images，找到你要推的镜像的 IMAGE ID
正确打标签：docker tag <image_id> your-dockerhub-username/myapp:latest</image_id>
注意：repository 名只能含小写字母、数字、短横线（-）和下划线（_），不能有大写或点号（.），否则 push 会报 invalid reference format
如果你用的是组织名（比如 acme/myapp），确保该组织下你有 Member 或 Owner 权限，否则 push 会被拒绝

常见于国内网络直连 DockerHub 不稳定，不是配置错误，而是连接层被干扰。Docker CLI 默认不显示详细传输日志，容易误判为“卡死”。

加 -D 参数看底层请求：docker push -D your-dockerhub-username/myapp:latest，能看到是否卡在 POST /v2/.../blobs/uploads/
临时换 registry mirror 不起作用 —— docker push 是直连目标 registry 的，镜像加速器只影响 pull
可改用 curl + docker save 手动上传（麻烦但可控）：先 docker save myapp | gzip > myapp.tar.gz，再用 curl -X POST ... 走 DockerHub API 分块上传（适合 CI 中绕过 CLI 限制）
更实际的解法：开一个干净的代理终端（如 export HTTP_PROXY=<a href="https://www.php.cn/link/ee5b912101bea6d7649532c3234c7fce">https://www.php.cn/link/ee5b912101bea6d7649532c3234c7fce</a>），再跑 docker push，比折腾配置文件快得多

DockerHub 免费账户单次 push 有 10 分钟活跃窗口限制，大镜像（尤其含 node_modules 或 pip install 结果）很容易超时。

检查分层：用 docker history your-image 看哪一层体积异常（比如某 RUN 指令占了 500MB）
多阶段构建必须用上：FROM golang:1.22 AS builder 编译，再 FROM alpine:3.20 COPY 二进制，别把整个 /go 目录 COPY 进去
删除包管理器缓存：RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*，或者用 apk --no-cache add curl
不要 COPY . /app 后再 RUN npm install —— 这会让 node_modules 改动就失效全部缓存；应先 COPY package*.json，再 RUN npm ci，最后 COPY .