本頁面由 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 編輯者角色外，還必須具備專案檢視者 IAM 角色。如要解決這個錯誤，請執行下列任一操作：

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

缺少服務帳戶權限，導致建構作業失敗

如果用於建構作業的服務帳戶沒有執行工作所需的權限，您會看到類似下列內容的錯誤：

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

如要修正這項錯誤，請將必要權限授予服務帳戶。請參閱下列頁面中的資訊，判斷要授予建構服務帳戶的權限：

嘗試使用 Cloud Build 部署時，建構服務帳戶權限不足，因此建構作業通常會失敗。

在 Cloud Run 函式上部署時發生權限遭拒錯誤

嘗試使用 Cloud Run 函式時，您會看到下列錯誤：

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

如要修正這項錯誤，請將 Cloud Run Functions 開發人員角色授予建構服務帳戶。

在 Cloud Run 函式上部署時發生權限不足錯誤

嘗試在 Cloud Run 函式上部署時，您會看到類似下列的錯誤：

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

如要解決這個錯誤，請將服務帳戶使用者角色授予使用者指定的服務帳戶或預設服務帳戶。

在 App Engine 上部署時發生錯誤

嘗試在 App Engine 上部署時，您會看到類似下列的錯誤：

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

如要解決這個錯誤，請將 App Engine 管理員角色授予使用者指定的服務帳戶或預設服務帳戶。

在 GKE 部署時發生錯誤

嘗試在 GKE 上部署時，您會看到類似下列的錯誤：

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

如要解決這個錯誤，請將 GKE 開發人員角色授予建構服務帳戶。

部署至 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 身分與存取權管理權限，因此無法執行建構觸發條件。如要解決這項錯誤，請將 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 控制台中開啟記錄檔探索工具：

前往記錄檔探索工具

在查詢欄位中輸入下列文字：

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 Builder。Docker 橋接器介面 (以及連線至這個介面的容器) 會獲派 192.168.10.0/24 的 IP 範圍，因此無法與相同子網路中的外部主機通訊。在設定私有集區時，為專案中的資源分配 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

如果建構作業嘗試存取私有網路中的資源，但失敗，就可能發生這個錯誤。根據預設，透過 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" } }

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

後續步驟

瞭解如何管理建構記錄。