本頁面由 Cloud Translation API 翻譯而成。

建構錯誤疑難排解

本頁面提供一些常見錯誤訊息的疑難排解策略以及解決方案，這些錯誤訊息可能會在您執行建構作業時顯示。

您是否查看過建構記錄？

使用記錄或 Cloud Storage 建構記錄，進一步瞭解建構錯誤。寫入 stdout 或 stderr 的記錄可使用 Google Cloud 控制台和 gcloud CLI 查看。

使用者無法存取建構記錄，因此手動建構失敗

嘗試手動執行建構作業時，會看到下列錯誤訊息：

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

發生這項錯誤的原因是，Cloud Build 規定執行手動建構作業並使用預設 Cloud Storage 記錄水桶的使用者，除了 Cloud Build 編輯者角色外，還必須具備專案檢視者 IAM 角色。如要解決這個錯誤，請執行下列任一操作：

使用預設記錄值區，並將「專案檢視者」角色和「Cloud Build 編輯者」角色授予執行建構作業的使用者。如需授予這項權限的操作說明，請參閱「設定 Cloud Build 資源的存取權」。
建立自己的 Cloud Storage bucket 來儲存記錄。如需操作說明，請參閱「將建構記錄儲存在使用者建立的值區中」。

缺少 `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 Functions 開發人員角色授予建構服務帳戶。

缺少 `cloudbuild.builds.create` 權限，因此無法觸發建構作業

執行建構觸發程序時，您會看到類似下列的錯誤訊息：

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

自動建構觸發條件會使用服務帳戶建立建構作業。這項錯誤表示服務帳戶缺少 cloudbuild.builds.create 身分與存取權管理權限，因此無法執行建構觸發條件。如要解決這項錯誤，請將 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 身分與存取權管理角色授予 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，找出負責移除權限或包含錯誤訊息所列權限的 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 權杖、安全殼層金鑰) 做為建構步驟。進一步瞭解如何存取私人的 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 橋接器介面 (以及連線至這個介面的容器) 會獲派 192.168.10.0/24 的 IP 範圍，因此無法與相同子網路中的外部主機通訊。在設定私有集區時，為專案中的資源分配 IP 範圍時，建議選取 192.168.10.0/24 以外的範圍。如需操作說明，請參閱「為私人集區設定環境」。

建構作業失敗，並顯示「已過期」錯誤訊息，且未顯示任何記錄

您觸發或提交建構作業，但作業失敗並擲回「Expired」錯誤，且未產生任何記錄。

請檢查設定中的下列項目：

您設定的 queueTtl 值較低 (例如 20 秒)。

請增加結構定義中的值，然後再次執行建構作業。詳情請參閱 queueTtl。
您嘗試執行的並行建構作業次數已達上限。

您可以透過 Google Cloud 控制台的「配額」頁面申請提高配額。詳情請參閱「配額與限制」。
您使用私人集區，並選擇非預設機器。

建構作業可能需要等待新的虛擬機器啟動，因此啟動時間可能會較長。詳情請參閱「機器類型」。

您可以嘗試變更機器類型。
您使用私人集區，並為集區指定 IP 範圍。

IP 的實體範圍決定集區中的工作站 VM 數量，因此即使低於「並行建構」配額，也會決定並行建構的限制。如果集區中沒有可用的工作站 VM，建構作業就會排入佇列。

如果指定子網路中的可用 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 Proxy 的位址 (例如 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 指令。

與虛擬私有雲網路對等互連的私人集區中，建構作業已加入佇列

在與您自己的虛擬私有雲網路對等互連的服務生產端網路中，執行私人集區的建構作業時，請務必確保這兩個網路之間的私人連線保持完整。如果刪除私人集區所依附的私人連線，私人集區可能會中斷。這可能會顯示為建構作業持續排隊，直到最終逾時為止。因此，如要刪除私人連線，請務必一併刪除所有私人集區，這些集區的服務供應商網路是透過這個私人連線連至您的虛擬私有雲網路。

嘗試核准或拒絕 2 個月前的待處理建構作業

您無法核准或拒絕 2 個月前的待處理建構作業。嘗試這麼做可能會導致系統顯示類似下方的錯誤訊息：

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

如果發生這種情況，請嘗試提交新版本。

後續步驟

瞭解如何管理建構記錄。