/etc/docker/daemon.json 必须存在且格式合法才能使 Docker 镜像加速生效；常见失效原因是文件缺失、权限错误或 JSON 格式非法，需用 sudo tee 创建并校验，配置后必须重启 docker 服务（sudo systemctl restart docker）并验证日志与拉取行为。
/etc/docker/daemon.json 必须存在且格式合法，否则 Docker 完全忽略镜像加速配置——这是唯一稳定生效的方式，其他操作都是临时或无效的。
为什么改了 daemon.json 却没加速？
最常见原因是文件根本没被读到：/etc/docker/daemon.json 默认不存在，Docker 启动时不报错也不提示，直接跳过；你手动创建但权限不对、JSON 格式非法（比如末尾多逗号、URL 少双引号、以 / 结尾），也会静默失败。
验证方法：sudo docker info | grep -A 1 "Registry Mirrors" 输出为空，基本就是这个原因。
- 先确保目录存在：
sudo mkdir -p /etc/docker - 用
sudo tee写入，避免权限问题：sudo tee /etc/docker/daemon.json - 用在线 JSON 校验器（如
https://www.php.cn/link/eca3738a60ea31de49a6ce118e914765）检查内容是否合法 - URL 必须是完整
https://开头，不能写成http://或漏掉协议
registry-mirrors 该填哪些地址？
不是所有“国内镜像站”都可用。网易 hub-mirror.c.163.com 已停更；阿里云地址必须登录控制台获取专属链接（形如 https://xxx.mirror.aliyuncs.com）；腾讯云 mirror.ccs.tencentyun.com 仅限其云内服务器稳定使用。
2026 年 6 月实测仍公开可用、无需注册的地址：
-
https://docker.xuanyuan.me（轩辕镜像，专线稳定） -
https://docker.1ms.run（毫秒镜像，低延迟） -
https://docker.m.daocloud.io（DaoCloud 新源，替代旧版）
建议填 2–3 个，Docker 按数组顺序尝试，第一个不可用时自动 fallback，但别堆太多——探测耗时反而拖慢首次拉取。
改完配置必须重启 docker 服务
sudo systemctl daemon-reload 没用，它只重载 systemd unit 文件，不触发 Docker 守护进程重新读取 daemon.json。
Docker 只在启动时加载该文件，运行中修改完全无效。
- 必须执行：
sudo systemctl restart docker（生产环境首选） - 调试时可手动启停：
sudo pkill dockerd && sudo dockerd，但别在正式环境这么干 - 重启后检查日志：
sudo journalctl -u docker --since "30 seconds ago" | grep mirror，能看到加载记录才算真正生效
验证加速是否真起作用
光看 docker info 输出还不够。有些镜像（尤其是冷门或新 tag）在加速器上还没缓存，首次拉取仍走 registry-1.docker.io，速度没变化——这不是配置失败，而是镜像未命中缓存。
真正有效的验证方式：
- 拉一个高频镜像：
docker pull nginx:alpine，观察下载过程中的域名（终端会显示类似docker.xuanyuan.me/v2/...） - 再拉一次同一镜像：
docker pull nginx:alpine，第二次应明显更快，说明缓存已生效 - 如果始终看到
registry-1.docker.io，说明请求根本没走镜像源，回溯检查daemon.json路径、格式、重启动作
复杂点在于：不同镜像源同步策略不同，有的全量同步，有的只同步热门镜像。选源时得看你要拉什么——不是所有加速器都“全能”。
