Java 8 已停止支援，並將於 2026 年 1 月 31 日
淘汰。淘汰後，您將無法部署 Java 8 應用程式，即使貴機構先前使用機構政策重新啟用舊版執行階段的部署作業也一樣。現有的 Java 8 應用程式在
淘汰日期後，仍會繼續執行並接收流量。建議您
改用最新支援的 Java 版本。
遷移至以 gcloud CLI 為基礎的 Gradle 外掛程式
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
如果您先前使用以 Java App Engine SDK 為基礎的外掛程式 (com.google.appengine.appengine-gradle)，但想改用新的 Google Cloud CLI，請遷移到以 gcloud CLI 為基礎 (com.google.cloud.tools.appengine-gradle) 的外掛程式。
以 gcloud CLI 為基礎的外掛程式的優點
升級至新的外掛程式可提供下列優點：
使用的驗證憑證與所有其他以 gcloud CLI 為基礎的指令相同，這些憑證是從標準 gcloud auth login 流程產生的。
支援 App Engine 彈性環境。
在標準 gcloud CLI 更新流程中自動更新本機開發伺服器。
支援部署 App Engine 服務 (Cron、佇列、DoS 保護、分派) 設定，而且不會影響到您的服務。
重要差異
在您遷移之前，請注意以下重要差異：
- gcloud CLI 依附元件
- 除了 Java 之外，舊外掛程式會在沒有任何特定本機環境依附元件的情況下執行，但新外掛程式會要求安裝 gcloud CLI。
- 不會產生 Endpoints 探索文件
- 新外掛程式不會產生 Endpoints 探索文件，這是單獨外掛程式的一個特色。執行 Endpoints 後端不再需要在建構步驟中產生這個檔案，因為伺服器現在會在執行階段產生這個檔案。只有當您需要為 iOS 或 Android 等作業系統產生用戶端程式庫時，才應使用新外掛程式。如要進一步瞭解新外掛程式，請參閱遷移至 App Engine 適用的 Endpoints Frameworks 指南。
- 目前已停止支援 EAR 檔案格式
- 新外掛程式已不再支援 EAR 檔案格式，無法同時執行及部署多項服務。
- 新部署指令
- 舊外掛程式會呼叫
appcfg 指令來部署應用程式，而新外掛程式則會使用新 gcloud CLI 來部署應用程式。 - 必須手動設定 JPA/JDO Datanucleus 強化功能
- 如果您的專案使用
gradle-appengine-plugin 的 JPA/JDO Datanucleus 強化功能，在改用以 gcloud CLI 為基礎的外掛程式之後，您必須手動設定 Datanucleus 強化功能。請參閱 Stackoverflow 中的示例。 - 不支援 Android Studio
- 您可以讓 Android Studio 專案改用新外掛程式，但 Android Studio App Engine 開發伺服器和部署支援不適用於這個新外掛程式。如要執行及部署應用程式，您必須直接叫用 Gradle。
系統支援使用 XML 設定檔，但不支援 YAML。
遷移至新外掛程式
從 build.gradle 檔案中移除舊的 gradle-appengine-plugin 設定與匯入項目。
將新外掛程式新增至 build.gradle 檔案 buildscript 區段的 classpath：
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
}
}
在服務的根目錄下，執行下列指令，確認您是否能在本機執行應用程式：
gradle appengineRun
在 build.gradle 檔案的 buildscript 區段中，指定專案 ID 與版本來設定部署：
appengine {
deploy {
version = 'v1'
project = "your GCP project ID"
}
}
新工具會忽略 appengine-web.xml 檔案中的應用程式與版本元素。
在服務的根目錄下，執行下列指令，確認您是否能部署應用程式：
gradle appengineDeploy
遷移以 EAR 為基礎的多服務設定
新外掛程式不支援 EAR 套件，而是支援在本機執行多項服務，而不需要執行任何特殊的套件步驟。
如何遷移以 EAR 為基礎的 Gradle 專案：
挑選將負責執行其餘服務的主要服務。建議您選取預設服務，但也可以選擇一起執行的任何服務。
在 appengine 設定中，修改 run.services 項目，加入應由本機開發伺服器執行的所有服務。
示例專案結構如下：
../{projectRoot}/
build.gradle
settings.gradle (includes default-service & secondary-service)
{your-default-service}/build.gradle {includes appengine-gradle-plugin}
….
{your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml
{your-secondary-service}build.gradle {includes appengine-gradle-plugin}
….
{your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml
範例 build.gradle buildscript 如下：
appengine {
run {
// configure the app to point to the right service directories
services = [
projectAsService(project),
projectAsService(":another-module")
]
}
}
// helper method to obtain correct directory and set up dependencies
def getExplodedAppDir(Project serverProject) {
// if not 'this' module, then do some setup.
if (serverProject != project) {
// make sure we evaluate other modules first so we get the right value
evaluationDependsOn(serverProject.path)
// make sure we build "run" depends on the other modules exploding wars
project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar
}
return serverProject.tasks.explodeWar.explodedAppDirectory
}
以 App Engine SDK 為基礎和以 gcloud CLI 為基礎的 Gradle 指令比較
下表根據您使用的是 App Engine SDK 為基礎的 Gradle 外掛程式，還是 以 gcloud CLI 為基礎的 Gradle 外掛程式，列出了叫用 Gradle 外掛程式的不同方式。
後續步驟
- 現在您已成功遷移至新外掛程式，接下來可以測試及部署應用程式。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-09-04 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-04 (世界標準時間)。"],[[["\u003cp\u003eMigrate from the Java App Engine SDK-based plugin (\u003ccode\u003ecom.google.appengine.appengine-gradle\u003c/code\u003e) to the gcloud CLI-based plugin (\u003ccode\u003ecom.google.cloud.tools.appengine-gradle\u003c/code\u003e) for enhanced benefits, including unified authentication, flexible environment support, and automatic updates.\u003c/p\u003e\n"],["\u003cp\u003eThe new gcloud CLI-based plugin requires the gcloud CLI to be installed and no longer supports Endpoints discovery doc generation within the plugin, as it's now handled at runtime, nor does it support the EAR file format for multiple services.\u003c/p\u003e\n"],["\u003cp\u003eManual configuration of Datanucleus enhancement is necessary if your project uses JPA/JDO, and Android Studio's built-in App Engine support is incompatible, requiring direct Gradle invocation.\u003c/p\u003e\n"],["\u003cp\u003eMigrating from EAR-based multi-service configurations to the new plugin involves selecting a primary service and configuring the \u003ccode\u003erun.services\u003c/code\u003e entry in your \u003ccode\u003ebuild.gradle\u003c/code\u003e to include all services for local development, replacing EAR packaging entirely.\u003c/p\u003e\n"],["\u003cp\u003eThe gcloud CLI-based plugin uses new Gradle commands like \u003ccode\u003eappengineRun\u003c/code\u003e for local development and \u003ccode\u003eappengineDeploy\u003c/code\u003e for deployment, replacing the old SDK-based commands such as \u003ccode\u003eappengine:devserver\u003c/code\u003e and \u003ccode\u003eappengine:update\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Migrating to the gcloud CLI-based Gradle plugin\n\nIf you previously used the Java App Engine SDK-based plugin\n(`com.google.appengine.appengine-gradle`) and want to move to the new\n[Google Cloud CLI](/sdk/downloads), migrate to the gcloud CLI-based\n(`com.google.cloud.tools.appengine-gradle`) plugin.\n\nBenefits of the gcloud CLI-based plugin\n---------------------------------------\n\nUpgrading to the new plugin provides the following benefits:\n\n- Uses the same authentication credentials as all other gcloud CLI\n -based commands, which are produced from the standard `gcloud auth login`\n flow.\n\n- Supports the App Engine flexible environment.\n\n- Updates the local development server automatically as part of the standard\n gcloud CLI update flow.\n\n- Supports deploying App Engine service (cron, queues, dos, dispatch)\n configurations, independently from your service.\n\nNotable differences\n-------------------\n\nBefore you migrate, be aware of these notable differences:\n\ngcloud CLI dependency\n: The old plugin runs without any specific local environment dependencies,\n besides Java, but the new plugin requires that you have the\n gcloud CLI installed.\n\nNo Endpoints discovery doc generation\n: The new plugin does not generate Endpoints discovery docs, a\n feature available in a separate plugin. Running your Endpoints\n backend no longer requires generating this file in a build step as the server\n now generates it at runtime. You should use the new plugin only if you need\n to generate client libraries such as for iOS or Android. Learn more about the\n new plugins by reviewing the [Migrating to Endpoints Frameworks for\n App Engine](/endpoints/docs/frameworks/legacy/v1/java/migrating)\n guide.\n\nEAR file format no longer supported\n: The new plugin no longer supports the\n EAR file format for running and deploying multiple services at the same time.\n\nNew deployment command\n: The old plugin calls the `appcfg` command to deploy\n applications, while the new plugin deploys using the new gcloud CLI.\n\nJPA/JDO Datanucleus enhancement must be manually configured\n: If your project\n uses the `gradle-appengine-plugin`'s JPA/JDO Datanucleus enhancement, you must\n manually configure Datanucleus enhancement after switching to the\n gcloud CLI-based plugin. See an [example from Stackoverflow](https://stackoverflow.com/questions/29279503/how-can-i-run-datanucleus-enhancer-from-gradle).\n\nAndroid Studio is not supported\n: You can switch your Android Studio project to use the new plugin, but the\n Android Studio App Engine development server and deployment support\n does not work with this new plugin. To run and deploy your app, you have to\n invoke Gradle directly.\n\nUse of XML configuration files is supported, but not YAML.\n\nMigrating to the new plugin\n---------------------------\n\n1. Remove the old `gradle-appengine-plugin` configuration and imports from your\n `build.gradle` file.\n\n2. Add the new plugin to the `classpath` of your `build.gradle` file's\n `buildscript` section:\n\n buildscript {\n repositories {\n mavenCentral()\n }\n\n dependencies {\n classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'\n }\n }\n\n3. At the root of your service, run the following command to verify that you can\n run your app locally:\n\n gradle appengineRun\n\n4. In your `build.gradle` file's `buildscript` section, configure your\n deployment by specifying your project ID and version:\n\n appengine {\n deploy {\n version = 'v1'\n project = \"your GCP project ID\"\n }\n }\n\n The new tooling ignores the application and version elements in your\n `appengine-web.xml` file.\n5. At the root of your service, run the following command to verify that you can\n deploy your application:\n\n gradle appengineDeploy\n\nMigrating EAR based multi-service configurations\n------------------------------------------------\n\nThe new plugin does not support EAR packaging. Instead, it supports running\nmultiple services locally without any special packaging steps.\n\nTo migrate your EAR-based Gradle project:\n\n1. Pick a primary service that will be responsible for running the rest of the\n services. You should select your default service, but it can be any of the\n services that are run together.\n\n2. In your `appengine` configuration, modify the `run.services` entry to include\n all the services that should be run by the local development server.\n\n An example project structure: \n\n ../{projectRoot}/\n build.gradle\n settings.gradle (includes default-service & secondary-service)\n {your-default-service}/build.gradle {includes appengine-gradle-plugin}\n ....\n {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml\n {your-secondary-service}build.gradle {includes appengine-gradle-plugin}\n ....\n {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml\n\n An example `build.gradle` buildscript: \n\n appengine {\n run {\n // configure the app to point to the right service directories\n services = [\n projectAsService(project),\n projectAsService(\":another-module\")\n ]\n }\n }\n\n // helper method to obtain correct directory and set up dependencies\n def getExplodedAppDir(Project serverProject) {\n // if not 'this' module, then do some setup.\n if (serverProject != project) {\n // make sure we evaluate other modules first so we get the right value\n evaluationDependsOn(serverProject.path)\n // make sure we build \"run\" depends on the other modules exploding wars\n project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar\n }\n return serverProject.tasks.explodeWar.explodedAppDirectory\n }\n\nApp Engine SDK-based vs gcloud CLI-based Gradle commands\n--------------------------------------------------------\n\nThe following table shows the different ways you invoke the Gradle plugin,\ndepending on whether you use the App Engine SDK-based Gradle plugin or\nthe [gcloud CLI-based Gradle](/appengine/docs/legacy/standard/java/using-gradle)\nplugin.\n\nWhat's next\n-----------\n\n- Now that you have migrated to the new plugin successfully, you can [test](/appengine/docs/legacy/standard/java/using-gradle#testing_gradle_app) and [deploy](/appengine/docs/legacy/standard/java/using-gradle#deploying_gradle_app) your application."]]
