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 的 Gradle 命令与基于 gcloud CLI 的 Gradle 命令
下表展示了调用基于 App Engine SDK 的 Gradle 插件或基于 gcloud CLI 的 Gradle 插件来完成各项操作时所用命令的不同。
后续步骤
- 现在，您已成功迁移到新插件。接下来，您可以测试和部署您的应用。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-21。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-21。"],[[["\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."]]
