Docker login 401 错误需用 Personal Access Token 替代密码，Username 填用户名非邮箱；push 失败多因 tag 格式错误（须为 username/repo:tag）、权限不足或网络问题；大镜像应优化分层、启用多阶段构建并清理缓存。
docker login 失败：401 Unauthorized 怎么办
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” 删除）
docker tag 格式不对，push 时提示 repository does not exist
镜像推送到 DockerHub，必须带完整命名空间，格式是 username/repository:tag。本地构建的镜像默认只有 myapp 这种名字，不加前缀 push 肯定失败。
- 查看当前镜像 ID：
docker images，找到你要推的镜像的IMAGE ID - 正确打标签：
docker tag <IMAGE_ID> your-dockerhub-username/myapp:latest - 注意：repository 名只能含小写字母、数字、短横线（
-）和下划线（_），不能有大写或点号（.），否则 push 会报invalid reference format - 如果你用的是组织名（比如
acme/myapp），确保该组织下你有Member或Owner权限，否则 push 会被拒绝
docker 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，比折腾配置文件快得多
Dockerfile 构建后镜像太大，push 耗时太久还常中断
DockerHub 免费账户单次 push 有 10 分钟活跃窗口限制，大镜像（尤其含 node_modules 或 pip install 结果）很容易超时。
- 检查分层：用
docker history your-image看哪一层体积异常（比如某 RUN 指令占了 500MB） - 多阶段构建必须用上：
FROM golang:1.22 AS builder编译，再FROM alpine:3.20COPY 二进制，别把整个/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 .
镜像层越多、每层越细粒度，push 时复用率越高；但 layer 数量超过 50 层，DockerHub 后端解析也会变慢 —— 这个边界值很少被文档提及，但实测会影响成功率。
