幾項因素可能會導致 App Engine 中的部署錯誤，包括缺少權限、組織政策變更，以及應用程式設定問題。
本頁面說明 App Engine 中的常見部署錯誤，以及解決這些錯誤的方法：
權限錯誤
本節說明在部署應用程式時，因缺少帳戶權限或機構政策異動而可能發生的錯誤。
如要找出您用來存取 Google Cloud CLI 和其他 Google Cloud Platform 工具的有效帳戶，請執行下列任一操作：
如果您使用 Google Cloud CLI 進行部署，請執行
gcloud auth list指令。如果您是透過 IDE 部署，請查看 Cloud Tools 外掛程式的設定。
如要瞭解為何在某些情況下，僅指派 App Engine 部署者 (roles/appengine.deployer) 角色可能不足以滿足需求，請參閱「App Engine 角色」一文。
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。
新專案無法部署
在新專案中首次部署應用程式時，您可能會看到下列錯誤：
ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT_ID.appspot.com"; service account PROJECT_ID@appspot.gserviceaccount.com does not have access to the bucket
如要解決這個問題，請將「Storage 管理員」(roles/storage.admin) 角色授予預設服務帳戶。詳情請參閱「將建構記錄儲存在使用者建立的值區」。
如果您已授予「儲存空間管理員」角色，以及其他必要角色 (根據您在部署期間遇到的不同權限錯誤)，但仍無法部署應用程式，可能是因為機構政策發生了以下變更：
自 2024 年 5 月起， Google Cloud 會為所有機構資源強制執行預設安全的機構政策。這項政策可防止 App Engine 將
Editor角色授予 App Engine 預設服務帳戶。2024 年 6 月，Cloud Build 變更了 Cloud Build 在新專案中使用服務帳戶的預設行為。如需詳細資訊，請參閱「Cloud Build 服務帳戶異動」。這項異動後，首次部署版本的新專案可能會使用預設 App Engine 服務帳戶，但該帳戶缺乏部署版本所需的權限。
如要解決這個問題，請按照下列步驟操作：
將
Editor角色授予 App Engine 預設服務帳戶 (PROJECT_ID@appspot.gserviceaccount.com)。請參閱 Cloud Build 的相關指南，瞭解如何變更預設服務帳戶，以及在新專案中停用預設變更。
呼叫端沒有權限存取專案
如果服務帳戶沒有在目前專案中部署應用程式的權限，就會發生以下錯誤：
User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist).
如要解決這個問題，請將 App Engine 部署者 (roles/appengine.deployer) 角色授予服務帳戶。
無法從註冊表擷取中繼資料
如果您使用沒有 Storage 管理員 (roles/storage.admin) 角色的服務帳戶執行 gcloud app deploy 指令，系統會發生以下錯誤：
Failed to fetch metadata from the registry, with reason: generic::permission_denied
如要解決這個問題，請將 Storage 管理員角色授予服務帳戶。
服務帳戶必須具備映像檔的權限
部署應用程式時發生下列錯誤：
The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME
導致這個錯誤的原因如下：
預設的 App Engine 服務帳戶沒有 Storage 物件檢視者 (
roles/storage.objectViewer) 角色。如要解決這個問題，請將 Storage 物件檢視者角色授予服務帳戶。
您的專案設有 VPC Service Controls 服務範圍，可透過存取層級限制 Cloud Storage API 存取權。
如要解決這個問題，請將用於部署應用程式的服務帳戶新增至對應的 VPC Service Controls 服務範圍 accessPolicies。
2024 年 5 月 15 日之後，如果專案先前未使用過 Container Registry，專案中的
gcr.io網域映像檔就會由 Artifact Registry 託管。 Google Cloud 如果您在 2019 年 12 月 1 日後建立的新專案中部署現有應用程式，服務帳戶可能沒有部署應用程式所需的權限。如要授予必要權限，請參閱「部署至 App Engine」一文。
無法建立 Cloud Build
如果您使用沒有 Cloud Build 編輯者 (roles/cloudbuild.builds.editor) 角色的服務帳戶執行 gcloud app deploy 指令，系統會發生下列錯誤。
Failed to create cloud build: Permission denied
如要解決這個問題，請將 Cloud Build 編輯者角色授予服務帳戶。
擷取應用程式時發生錯誤
如果用來部署應用程式的服務帳戶沒有 App Engine 部署者角色，就會發生以下錯誤。
Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project.
If you are running Google Cloud CLI version 328 or later, the following error occurs
when you deploy your app:
make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.
如要解決這個問題，請將 App Engine 部署者角色授予用來部署應用程式的服務帳戶。
使用無伺服器虛擬私有雲存取連接器部署服務時發生錯誤
如果使用者或服務帳戶嘗試透過無伺服器虛擬私有雲存取連接器部署應用程式，但缺少必要權限，就會發生以下錯誤：
Please ensure you have [compute.globalOperations.get] on the service project
如要解決這個問題，請確認用於部署的使用者或服務帳戶具有「無伺服器 VPC 存取權使用者」和「Compute 檢視器 IAM」 角色。
等待應用程式基礎架構進入良好的健康狀態時逾時
部署應用程式時發生下列錯誤：
Timed out waiting for the app infrastructure to become flex_await_healthy
這類錯誤可能由多種因素造成，例如缺少權限、程式碼錯誤、CPU/記憶體不足或健康狀態檢查失敗。
如要解決這個問題，請排除下列可能原因：
請檢查專案的機構政策是否限制外部 IP 位址的存取權。詳情請參閱「App Engine 彈性環境的已知問題」。
請確認您已為用於執行應用程式的服務帳戶 (通常是預設服務帳戶
app-id@appspot.gserviceaccount.com) 授予下列角色：如果服務帳戶沒有其他角色，請根據部署錯誤授予這些角色。
如果您在共用虛擬私有雲設定中部署，並在
app.yaml檔案中設定instance_tag，請參閱「在共用虛擬私有雲設定中部署時發生無效值錯誤」一文，瞭解如何修正問題。
在執行中的版本下重新啟動執行個體時發生錯誤
部署應用程式時發生下列錯誤：
error when restarting the instance under the running versions
自 2024 年 5 月起， Google Cloud 會針對所有新機構強制執行預設安全的機構政策。這項政策要求新專案中建立的所有 VM 執行個體都必須啟用 VM 管理員。對於新專案和現有專案，這項限制可防止中繼資料更新在專案或執行個體層級停用 VM 管理員。
如要解決這個問題，您必須停用「需要 OS 設定」(constraints/compute.requireOsConfig) 的機構政策限制。
如果這個問題持續發生，您也必須停用下列可能已在專案或機構層級啟用的機構政策：
定義 VM 執行個體可用的外部 IP (
constraints/compute.vmExternalIpAccess)。如果應用程式已設定為只使用私人網路，則不必停用這項限制。停用 Compute Engine 中繼資料的訪客屬性 (
constraints/compute.disableGuestAttributesAccess)
所需的 compute.firewalls.list 權限
在共用虛擬私有雲網路上部署應用程式時，會發生以下錯誤：
Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'
如果主專案的下列服務帳戶沒有 Compute 網路使用者 (roles/compute.networkUser) 角色，就會發生這個錯誤：
如要解決這個問題，請將「Compute 網路使用者」角色授予主機專案的 Google API 服務代理人和 App Engine 彈性環境服務代理人服務帳戶。
因機構政策限制而導致部署失敗
部署應用程式時發生下列錯誤：
ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/VERSION/projects/PROJECT_ID/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project PROJECT_ID.
這可能是因為部署應用程式時，系統會強制執行 constraints/compute.disableGuestAttributesAccess 限制。App Engine 彈性環境中的所有應用程式預設會強制執行這項組織政策。
如要解決這個問題，您必須停用 constraints/compute.disableGuestAttributesAccess 限制條件。
常見的部署錯誤
本節說明應用程式或專案設定錯誤的疑難排解策略。
在共用虛擬私有雲設定中部署時發生無效值錯誤
部署應用程式時，Cloud Logging 會針對彈性 VM 執行個體顯示下列錯誤：
Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert
這是已知問題，在 app.yaml 檔案中設定 instance_tag 會導致建立例項時發生錯誤。
如要解決這個問題，請從 app.yaml 檔案中移除 instance_tag 欄位，然後重新部署。
部署最多三個執行個體的應用程式時發生錯誤
如果應用程式在部署時將 max_instances 設為三個或更少，可能會發生非預期的錯誤或服務中斷情況。如要解決這個問題，請在 app.yaml 檔案中指定至少四個最大執行個體，然後重新部署。
超過上限執行個體限制
部署應用程式時發生下列錯誤：
You may not have more than 'xx' total max instances in your project.
每個專案可建立的執行個體數量有上限。如果您超過此上限，建立其他執行個體的要求就會失敗。
如要解決這個問題，請將 app.yaml 檔案中的 max_instances 值設為低於此限制的值，或是刪除部分服務或版本，讓 max_instances 的總和低於限制。
部署期間的建構作業失敗，但記錄中沒有錯誤
部署應用程式時發生下列錯誤：
ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details
如果您點選錯誤訊息中的連結，發現所有建構步驟都成功，但應用程式仍無法建構，可能是因為下列任一原因：
- 您使用客戶自行管理的加密金鑰 (CMEK)。
- 您為
staging.PROJECT_ID.appspot.com值區設定資料保留政策。
如要解決這個問題，請變更儲存桶的下列設定：
部署至現有 App Engine 版本時發生錯誤
在 App Engine 彈性環境中部署至現有版本時，可能會發生以下錯誤：
ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy
這項錯誤表示，使用正常運作的 Docker 映像檔更新不健康的部署作業，不一定會產生正常運作的部署作業。結果取決於不健康部署作業的執行個體狀態。即使發生錯誤，如果您提供良好的 Docker 映像檔，部署作業最終可能會恢復正常。雖然允許使用新版 Docker 映像檔更新現有版本，但這並非最佳做法。版本失敗時不會復原。
在共用虛擬私有雲設定中部署時發生內部 IP 錯誤
在服務專案中使用預設私人 IP 位址設定 (private-ranges-only) 時，如果要部署至共用虛擬私人雲端網路設定，可能會發生下列錯誤。
ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred.
這項錯誤可能表示共用虛擬私有雲主機專案中的 App Engine 彈性環境服務代理無法使用。已移除 App Engine 彈性環境服務代理人，或是未在主機專案中啟用 App Engine API。
如何解決這個問題：
- 在共用虛擬私有雲網路的主機專案中啟用 App Engine API。
- 如果已啟用 App Engine API，App Engine 彈性環境服務代理人就不會出現在專案中。請參閱「還原服務代理所需的角色」。