macOS Docker 配置国内镜像：服务选择、验证与回退
2026-09-10 资料核对：中科大官方帮助页已说明镜像缓存服务关闭；阿里云公告对加速器的使用环境与可拉取范围作出限制。本文不再将旧公共地址列表当作当前可用清单。以下配置须使用你已确认可用且信任的服务，本次未在你的目标网络完成镜像拉取实测。
Docker Desktop for Mac 的镜像加速配置在它管理的 Docker Engine 中生效。原文所用 macOS Catalina 和 Docker 19 的界面仅代表历史环境，本次改为不依赖旧截图的配置说明。
先分清镜像源解决哪一层问题
Docker Hub 镜像加速、Docker 软件安装源、容器内的软件包源，是三种不同配置。registry-mirrors 用于 Docker Engine 拉取 Docker Hub 镜像时的镜像服务，不会自动解决其他仓库、GitHub 下载或构建步骤中的网络问题。
一份能解析的 JSON 不代表镜像服务可用；docker info 显示地址也只说明守护进程读取了配置。镜像内容是否齐全、标签是否更新、你的网络和账户是否获准使用，仍需分别确认。
1. 检查当前上下文
docker context show
docker version若当前上下文指向远程服务器，在本机 Docker Desktop 修改设置不会改变远程守护进程。先确认操作对象。
2. 通过 Docker Desktop 设置配置
打开 Docker Desktop → Settings → Docker Engine，保存当前 JSON 的副本，再合并以下字段。不要在 macOS 主机上自行创建 /etc/docker/daemon.json 并假设它会被 Desktop 使用。
{
"registry-mirrors": [
"https://your-authorized-mirror.example.com"
]
}上面的 example.com 地址是格式占位符，不能直接使用。请替换为你获准使用的真实 HTTPS 地址；将字段合并进原有 JSON，保留其他配置并避免重复键。
确认可中断当前容器任务后，使用 Apply & restart 应用。代理设置与 registry-mirrors 作用不同，需要时按照 Docker Desktop 官方网络设置分别配置。
验证、排错与回退
docker info --format "{{json .RegistryConfig.Mirrors}}"
docker pull hello-world:latest
docker image inspect hello-world:latest --format "{{json .RepoDigests}}"第二步只拉取镜像，不会运行容器。记录时间、Docker 版本和错误信息。镜像可能已经存在于本地，成功也可能来自上游回退，因此单凭一次成功不能证明某个镜像站的速度或命中情况。
- 配置后无法启动：先检查 JSON 语法，恢复修改前的配置。
- 超时或名称解析失败：分别排查服务地址、DNS、守护进程代理与网络。
- unauthorized / denied：确认服务授权、登录方式和镜像范围。
- manifest unknown：核对仓库名、标签和平台支持；不要仅靠反复换源解决。
如需撤销，只撤回本次添加或修改的镜像配置，再重新应用。不要清空所有镜像、容器或卷作为常规排错方式。