Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

排查构建错误

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

您是否查看了构建日志？

使用 Logging 或 Cloud Storage 构建日志可以获取有关构建错误的详细信息。写入 stdout 或 stderr 的日志可以使用控制台和 gcloud CLI 查看。 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 存储桶来存储日志。如需了解相关说明，请参阅将构建日志存储在用户创建的存储桶中。

由于缺少 `iam.serviceAccounts.actAs` 权限，构建失败

您尝试使用 Cloud Run 或 App Engine 等托管式服务部署构建时看到以下错误：

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

若要解决此错误，请将您指定的 Cloud Build 服务账号或默认 Cloud Build 服务账号配置为模拟您用于构建的代管式服务的服务帐号。如需详细了解此任务，请参阅为托管式服务配置 Cloud Build 服务帐号模拟。

如需详细了解服务账号和权限，请参阅以下主题：

在 Cloud Run 函数上部署时出现“权限被拒”错误

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

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

若要解决此错误，请向您的构建服务账号授予 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 服务代理被删除或缺少权限，则在提交构建时可能会导致以下错误。

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 以外的范围。如需查看相关说明，请参阅为专用池设置环境。

构建失败，并显示错误消息“已过期”，且不显示任何日志

您触发或提交构建，但构建失败，并抛出“已过期”错误，且未生成任何日志。

请检查配置中的以下内容：

您配置的 queueTtl 值较低（例如 20 秒）。

请增加架构中的值，然后再次运行构建。如需了解详情，请参阅 queueTtl。
您已达到并发构建的配额。

您可以通过控制台中的“配额”页面申请增加配额。 Google Cloud 如需了解详情，请参阅配额和限制。
您使用的是专用池，并且选择了非默认机器。

构建可能需要等待新的虚拟机启动，因此启动时间可能会更长。如需了解详情，请参阅机器类型。

您可以尝试更改机器类型。
您使用的是专用池，并且为该池指定了 IP 范围。

IP 的实际范围决定了池中的工作器虚拟机的数量，因此决定了并发构建的限制，即使该限制低于并发构建配额也是如此。如果池中没有可用的工作器虚拟机，构建将排队。

当指定子网中的可用 IP 地址完全用完，没有地址可供分配给新的 Cloud Build 工作器时，就会发生这种情况。请尝试增加子网中的范围，然后重新运行构建。

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

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

 Failed to connect to <external_domain>: Connection timed out

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

I/O 超时错误

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

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

当构建尝试访问专用网络中的资源但失败时，可能会发生此错误。默认情况下，通过 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。
您需要向构建服务帐号授予另一项权限。

由于配额限制，构建失败

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

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 网络对等互连的专用池中的构建已排队

在服务提供方网络与您自己的 VPC 网络对等互连的专用池中运行构建时，请务必确保这两个网络之间的专用连接保持完好无损。如果您删除了专用池所依赖的专用连接，则可能会破坏专用池。这可能会导致构建一直处于排队状态，直到最终超时。因此，如果您想删除专用连接，请确保同时删除所有使用此专用连接将其服务提供方网络连接到您自己的 VPC 网络的专用池。

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

您无法批准或拒绝超过 2 个月的待处理构建。如果您尝试这样做，可能会看到类似如下内容的错误消息：

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

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

未能创建专用池：工作器池未与 Service Networking API 对等互连

您尝试创建专用池。但是，您会收到以下错误消息：

Failed to create private pool private-worker-pool: generic::failed_precondition: network "projects/PROJECT_NAME/global/networks/vpc-scmdev-lab-vpc" is not peered to the service networking API; please check your configuration and the documentation for troubleshooting and setting up your pool

要使构建能够从 Virtual Private Cloud 网络访问私有资源，您必须在您的 Virtual Private Cloud 网络与专用池所在的 Virtual Private Cloud 网络之间建立对等互连连接。如需了解相关说明，请参阅在 VPC 网络与服务提供方网络之间建立专用连接。

后续步骤

了解如何管理构建日志。