此页面由 Cloud Translation API 翻译。

排查构建错误

本页面介绍问题排查策略，以及运行构建时可能看到的一些常见错误消息的解决方案。

您是否查看了构建日志？

使用 Logging 或 Cloud Storage 构建日志可以获取有关构建错误的详细信息。写入 stdout 或 stderr 的日志会自动显示在 Google Cloud 控制台中。

由于用户无权访问构建日志，手动构建失败

您尝试运行手动构建时看到以下错误：

AccessDeniedAccess denied. [EMAIL_ADDRESS] does not have storage.objects.get access to the Google Cloud Storage object.

您之所以看到此错误，是因为 Cloud Build 要求运行手动构建并使用默认 Cloud Storage 日志存储分区的用户除了具有 Cloud Build Editor 角色之外，还具有 Project Viewer IAM 角色。若要解决此错误，您可以执行以下任一操作：

使用默认日志存储分区，并向运行构建的用户授予 Project Viewer 角色和 Cloud Build Editor 角色。有关授予此权限的说明，请参阅配置对 Cloud Build 资源的访问权限。
创建您自己的 Cloud Storage 存储分区来存储日志。如需了解相关说明，请参阅将构建日志存储在用户创建的存储分区中。

由于缺少服务账号权限，构建失败

如果您为 build 使用的服务账号没有执行任务所需的权限，您将看到类似以下的错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE ACCOUNT]

要解决此错误，请向此服务账号授予必需的权限。使用以下页面中的信息来确定向 build 服务账号授予的权限：

由于缺少构建服务账号权限，构建失败通常在尝试使用 Cloud Build 部署时发生。

在 Cloud Run functions 上部署时出错

您在尝试使用 Cloud Run 函数时看到以下错误：

ResponseError: status=[403], code=[Ok], message=[Permission 'cloudfunctions.functions.get' denied]

若要解决此错误，请向 build 服务账号授予 Cloud Run Functions Developer 角色。

在 Cloud Run functions 上部署时出现权限缺失错误

您尝试在 Cloud Run functions 上部署时看到如下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE ACCOUNT]

如需解决此错误，请向用户指定的服务账号或默认服务账号授予 Service Account User 角色。

在 App Engine 上部署时出错

您尝试在 App Engine 上部署时看到如下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

若要解决此错误，请向用户指定的服务账号或默认服务账号授予 App Engine Admin 角色。

在 GKE 上部署时出错

您尝试在 GKE 上部署时看到如下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

若要解决此错误，请向 build 服务账号授予 GKE Developer 角色。

在 Cloud Run 上部署时出错

您尝试在 Cloud Run 上部署时看到如下错误：

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [SERVICE_ACCOUNT]

您之所以看到此错误，是因为您的 build 服务账号缺少在 Cloud Run 上部署所需的 IAM 权限。如需了解如何授予必要的权限，请参阅在 Cloud Run 上部署。

由于缺少 `cloudbuild.builds.create` 权限，构建触发器失败

运行构建触发器时，您看到类似以下错误：

Failed to trigger build: Permission 'cloudbuild.builds.create' denied on resource 'projects/xxxxxxxx' (or it may not exist)

构建触发器使用服务账号创建构建。此错误表示服务账号缺少 cloudbuild.builds.create IAM 权限，该服务账号需要此权限才能运行构建触发器。您可以通过向用户指定的服务账号或默认服务账号授予 Cloud Build Service Account IAM 角色来解决此错误。

由于缺少服务代理权限，构建提交失败

如果 Cloud Build 服务代理被删除或缺少权限，则可能会导致提交 build 时出现以下错误。

Caller does not have required permission to use project $PROJECT_ID. Grant the caller the roles/serviceusage.serviceUsageConsumer role, or a custom role with the serviceusage.services.use permission, by visiting https://console.developers.google.com/iam-admin/iam/project?project=$PROJECT_ID and then retry. Propagation of the new permission may take a few minutes.

在此场景中，调用方是 Cloud Build 服务代理。如需解决此权限问题，请按以下步骤操作：

确保 Cloud Build 服务代理存在。如需查看项目的服务代理，您可以前往 Google Cloud 控制台的 IAM 页面，然后选中显示 Google 管理的服务账号复选框。如果没有，您可以通过运行以下 gcloud CLI 命令来创建它：
```
gcloud beta services identity create --service=cloudbuild.googleapis.com \
    --project=PROJECT_ID
```

接下来，将 roles/cloudbuild.serviceAgent IAM 角色授予 Cloud Build 服务代理：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com" \
    --role="roles/cloudbuild.serviceAgent"

如果您想验证哪个 IAM 身份可能导致了服务代理权限问题，请按以下步骤操作：

在 Google Cloud 控制台中打开 Logs Explorer：

转到日志浏览器

在查询字段中输入以下文本：

resource.type="project"
log_name="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
"service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"

如果您在使用此查询后看到任何日志条目，请检查其中是否有任何条目正在从服务代理 (service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com) 中移除权限。如果有，请查看该日志中的 protoPayload.authenticationInfo.principalEmail，以确定负责移除相应权限的 IAM 身份，或包含错误消息中列出的权限的 roles/cloudbuild.serviceAgent 角色。

触发器失败并显示 `Couldn't read commit` 错误

运行构建触发器时您看到以下错误：

  Failed to trigger build: Couldn't read commit

如果您尝试使用不存在的分支触发构建，Cloud Build 会返回此消息。检查目录名称的拼写和一致性。如需了解触发器设置说明，请参阅创建和管理构建触发器。

无法创建 Pub/Sub 触发器

您在创建 Pub/Sub 触发器时看到以下错误：

  Failed to create trigger: Request is prohibited by organization's policy

此错误表示您的项目中 Pub/Sub API 受到限制。限制 Pub/Sub API 的项目会限制创建推送通知订阅的功能。您可以暂时从边界中的受限服务中移除 Pub/Sub，创建触发器，然后再次限制 Pub/Sub API 以解决错误。

在 Container Registry 中存储映像时出错

构建尝试将构建的映像存储到 Container Registry 时，您看到类似以下错误：

[EMAIL_ADDRESS] does not have storage.buckets.create access to project [PROJECT_NAME]

您之所以看到此错误，是因为您的 build 服务账号没有在 Container Registry 中存储容器映像所需的 Storage Admin 角色。

由于 SSH 授权无效，构建失败

运行构建时您看到以下错误：

Could not parse ssh: [default]: invalid empty ssh-agent socket, make sure SSH_AUTH_SOCK is set

此错误表示 SSH 授权存在问题。一个常见的示例是，通过 Cloud Build 访问私有 GitHub 代码库时发生的 SSH 授权错误。如需了解如何为 GitHub 设置 SSH，请参阅访问私有 GitHub 代码库。

由于 `No route to host` 错误，构建失败

在专用池中运行构建时，您会看到以下或类似错误：

Unable to connect to the server: dial tcp 192.168.10.XX:<port>: connect: no route to host

Cloud Build 使用 Docker 容器在 Google 管理的项目内的虚拟机上运行其 Cloud Build 构建器。Docker 桥接接口（以及因此连接到此接口的容器）分配的 IP 范围为 192.168.10.0/24，这使得无法与同一子网中的外部主机进行通信。在配置专用池期间，为项目中的资源分配 IP 范围时，我们建议选择 192.168.10.0/24 以外的范围。如需查看相关说明，请参阅为专用池设置环境。

由于未启用外部 IP，连接到外部资源失败

从专用池连接到外部资源时，您会看到以下错误：

 Failed to connect to <external_domain>: Connection timed out

私有池使用外部 IP 地址访问公共互联网上的资源，例如外部代码库。创建或更新专用池时，选中相应复选框即可向专用池分配外部 IP。如需了解如何在专用池中创建或更新字段，请参阅创建和管理专用池。

I/O 超时错误

运行构建时您看到以下错误：

Timeout - last error: dial tcp IP_ADDRESS: i/o timeout

如果您的 build 尝试访问专用网络中的资源但失败，则可能会发生此错误。默认情况下，通过 Cloud Build 运行的构建可以访问公共互联网中的私有资源，例如代码库或注册表中的资源。不过，只有在您使用专用池并将其配置为访问专用网络的情况下，构建才可以访问专用网络中的资源。请参阅在专用网络中使用 Cloud Build。

4xx 客户端错误

这组错误表示可能由于发送构建请求的用户一侧的错误而导致构建请求不成功。4xx 客户端错误的一些示例包括：

**Error**: 404 : Requested entity was not found
**Error**: 404 : Trigger not found
**Error**: 400 : Failed Precondition
**Error**: 403 : Permission denied

如果出现 4xx 客户端错误，请查看构建日志，看看其是否包含有关此错误原因的详细信息。导致客户端错误的一些常见原因包括：

您指定的来源位置没有任何新内容要提交，并且工作树干净。在这种情况下，请检查您的源代码位置，然后尝试再次构建。
您的代码库不包含构建配置文件。如果是这种情况，请将构建配置文件上传到您的代码库，然后再次运行构建。
您指定的触发器 ID 不正确。
您最近在安装 GitHub 应用后添加了新代码库，Cloud Build 无权访问新代码库。如果是这种情况，请将您的新代码库连接到 Cloud Build。
您需要向 build 服务账号授予另一项权限。

由于配额限制，构建失败

您看到以下错误，表示构建因特定区域的配额限制而失败：

Failed to trigger build: generic::failed_precondition: due to quota restrictions, cannot run builds in this region. Please contact support.

请与 Cloud Customer Care 联系，申请提高您在该特定区域的配额。如需详细了解配额和限制，请参阅配额和限制。

从 Docker 注册表拉取映像时出现超时问题

运行后，您在 Cloud Build 日志中看到以下超时错误：

Step #0: Pulling image: python:3.8.16-alpine3.17
Step #0: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

Step 1/7 : FROM python:3.8.16-alpine3.17
Get "https://registry-1.docker.io/v2/": dial tcp 34.205.13.154:443: i/o timeout

如需解决此错误，请使用 crane 下载 Docker 映像，然后继续将该映像加载到 Cloud Build Docker 映像上。

将以下代码段添加到 cloudbuild.yaml 文件中。

...
  # Crane runs as a regular user so we need to allow it to access the directory where it saves the image.
  - name: gcr.io/cloud-builders/docker
    args:
    - a+w
    - /workspace
    entrypoint: chmod
  # Use crane to download the image through the proxy
  - name: gcr.io/go-containerregistry/crane
    env: - 'HTTPS_PROXY=HTTPS_PROXY'
    args:
    - pull
    - 'python:3.8.16-alpine3.17'
    - /workspace/image.tar
  # Use docker load to add the image into the local Cloud Build registry
  - name: gcr.io/cloud-builders/docker
    args: [load, --input, "/workspace/image.tar"]
      - .

HTTPS_PROXY：HTTP 代理的地址（例如 https://proxy.example.com:8888/）。

映像加载后，您现有的 cloudbuid.yaml 步骤应会照常运行，例如

...
  - name: python:3.8.16-alpine3.17
    args:
    - echo
    - hello
    entrypoint: bash
  # Or use it internally on a Dockerfile
  - name: gcr.io/cloud-builders/docker
    args:
    - build

长时间运行的 Docker 步骤出现 `Unauthenticated` 错误

涉及运行时长超过一小时的 Docker 命令（例如将大型映像推送到 Artifact Registry）的构建步骤可能会因身份验证错误而失败。Cloud Build 每小时刷新一次身份验证令牌，但 Docker 可能无法获取这些新令牌，从而导致身份验证问题。您可以将自定义生命周期的令牌写入文件，并在 Docker 命令中引用该令牌。

与 VPC 网络对等互连的专用池中的队列化 build

当您在服务提供方网络与您自己的 VPC 网络对等互连的专用池中运行 build 时，请务必确保这两个网络之间的专用连接保持不变。如果您删除专用池依赖的专用连接，则会破坏专用池。这可能会显示为一直处于队列中的 build，直到最终超时。因此，如果您要删除专用连接，请务必一并删除服务提供方网络使用此专用连接连接到您自己的 VPC 网络的所有专用池。

尝试批准或拒绝超过 2 个月的待处理 build

您无法批准或拒绝超过 2 个月的待处理 build。尝试执行此操作可能会导致类似如下的错误消息：

 404, "message": "Requested entity was not
found.", "status": "NOT_FOUND" } }

如果出现这种情况，请尝试提交新的 build。

后续步骤

了解如何管理构建日志。