调用Google Cloud Artifact Registry REST API列Docker镜像遇404错误求助

算力阿峰

2026-6-26

解决GCP Artifact Registry Docker镜像列表API返回404的问题

以下是几个排查方向，对应你可能出现的操作错误：

检查Resource路径是否完整
你大概率漏掉了路径末尾的/dockerImages部分。正确的Resource格式必须包含这一后缀，完整路径示例：
projects/{PROJECT_ID}/locations/{LOCATION}/repositories/{REPO_NAME}/dockerImages
对应的curl请求应该是：
```
curl "https://artifactregistry.googleapis.com/v1/projects/your-project-id/locations/us-central1/repositories/your-repo-name/dockerImages" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)"
```
如果只写到repositories/{REPO_NAME}，请求的是仓库资源本身而非镜像列表API端点，必然触发404。
确认位置参数的准确性
Artifact Registry仓库绑定到具体区域（如us-central1）或多区域（如us），不能使用global作为位置参数。如果是多区域仓库，直接用多区域名称；单区域仓库必须填写精确的区域代码，不能用模糊的区域组名称。
核对项目ID和仓库名称
确保使用的是项目ID（而非后台显示的自定义项目名称），项目ID是GCP分配的唯一标识（比如my-gcp-project-123）。同时检查仓库名称拼写：Artifact Registry仓库仅允许小写字母、数字、连字符和下划线，且不能以特殊字符开头/结尾。
验证Artifact Registry API是否启用
若项目未启用该API，即使路径正确也会返回404。在GCP控制台的API库中搜索“Artifact Registry API”，确认状态为“已启用”。
排除权限伪装的404
虽然404通常与权限无关，但如果以上检查都没问题，可确认当前账号是否拥有artifactregistry.dockerImages.list权限（比如roles/artifactregistry.reader角色）。部分场景下，权限不足会被系统伪装成404错误，建议用拥有仓库读取权限的账号重新测试。