此页面由 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 存储分区来存储日志。如需了解相关说明，请参阅将构建日志存储在用户创建的存储分区中。

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

如果您用于构建的服务账号没有执行任务所需的权限，您将看到类似以下内容的错误：

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

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

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

在 Cloud Run functions 上部署时出现“权限遭拒”错误

您尝试使用 Cloud Run functions 时看到以下错误：

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]

您之所以看到此错误，是因为您的构建服务账号缺少在 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。

前往 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，以确定负责移除权限或包含错误消息中列出的权限的 roles/cloudbuild.serviceAgent 角色的 IAM 身份。

触发器失败并显示 `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，以解决此错误。

由于以下错误，无法从私有代码库中拉取或提取分支：`fatal: could not read Username`

尝试对私有代码库中的远程分支执行 git pull 或 git fetch 时，您会看到以下错误：

fatal: could not read Username for '<REMOTE_URL>': No such device or address

在私有代码库中，此错误是预期行为，因为在首次克隆代码库后，Git 凭据帮助程序会被有意移除。如需从私有代码库中提取远程分支，请手动设置授权凭据（API 令牌、SSH 密钥）作为构建步骤。详细了解如何访问私有 GitHub 代码库。

由于 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/）。

加载映像后，现有的 cloudbuild.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。

后续步骤

了解如何管理构建日志。