WSL2环境下执行docker build报错403 Forbidden但单独pull镜像正常

算力阿峰

2026-10-7

问题原因

该报错为Docker Desktop 3.6.0版本默认启用的BuildKit构建引擎的已知兼容问题：BuildKit拉取镜像元数据的认证、请求逻辑与独立的docker pull命令存在差异，即使单独拉取镜像正常，BuildKit也可能触发镜像仓库的权限校验拦截返回403错误。
部分场景下为BuildKit本地元数据缓存过期、第三方镜像加速源对BuildKit的manifest请求支持不完善导致。

解决方案

方案1：临时禁用BuildKit执行构建
执行构建命令前临时关闭BuildKit即可正常完成构建，不同环境命令如下：
- Linux/WSL环境：
```
DOCKER_BUILDKIT=0 docker build -t getting-started .
```
- Windows CMD环境：
```
set DOCKER_BUILDKIT=0
docker build -t getting-started .
```
- Windows Powershell环境：
```
$env:DOCKER_BUILDKIT=0
docker build -t getting-started .
```
方案2：清理BuildKit缓存后重试
执行以下命令清理BuildKit本地缓存，再重新执行构建命令即可：
```
docker builder prune
```
方案3：永久关闭BuildKit（适合频繁遇到该问题的场景）
1. 打开Docker Desktop设置面板，进入「Docker Engine」配置页
2. 将配置JSON中的"buildkit": true参数修改为"buildkit": false
3. 点击「Apply & Restart」重启Docker服务，后续构建默认使用传统构建引擎，不会再触发该错误
补充说明：如果配置了第三方Docker镜像加速源，可以先切换回Docker官方默认源后重试，部分加速源对BuildKit的manifest请求兼容性不足也会导致该报错。