Gretty 版本覆盖指南：如何替换 Jetty/Tomcat 与 Servlet API 版本

Gretty 版本覆盖指南：如何替换 Jetty/Tomcat 与 Servlet API 版本

【免费下载链接】grettyAdvanced gradle plugin for running web-apps on jetty and tomcat.项目地址: https://gitcode.com/gh_mirrors/gr/gretty

Gretty 是一款功能强大的 Gradle 插件，专为在 Jetty 和 Tomcat 上快速运行 Web 应用而设计，支持热部署、Spring Boot、多应用 Farm 等高级特性。很多开发者在使用 Gretty 时遇到的第一道坎，就是如何替换默认的 Jetty/Tomcat 容器版本，以及如何处理Servlet API 版本冲突。本文用最简方式带你掌握 Gretty 版本覆盖的完整套路，让你一次配置、处处生效。

为什么要手动覆盖 Gretty 的容器版本？

Gretty 默认内置了一套经过测试的 Jetty / Tomcat 版本（默认容器为 Jetty 9）。但在实际项目中，你往往需要：

• 与公司统一的技术栈对齐（比如统一使用 Tomcat 8）；
• 验证应用在不同 Servlet 容器上的兼容性；
• 修复特定 Jetty 版本的安全漏洞；
• 让本地开发环境与线上服务器版本完全一致。

Gretty 为此提供了两条并行的配置路径：切换容器类型与覆盖具体版本号。

Gretty 支持哪些 Jetty 与 Tomcat 版本？

根据 Gretty 的核心配置源码（libs/gretty/src/main/groovy/org/akhikhl/gretty/ServletContainerConfig.groovy），Gretty 内置了以下容器配置项：

注意：jetty9.3与jetty9.4仅在 Java 8 及以上环境中可用（源码中通过 Java 版本判断动态注册）。

方法一：一行配置切换 Jetty / Tomcat

最简单的替换方式，是在build.gradle的gretty配置块中指定servletContainer：

gretty { servletContainer = 'tomcat8' // 或 'jetty7'、'jetty8'、'jetty9'、'jetty9.3'、'jetty9.4'、'tomcat7' }

保存后重新执行gradle appRun，Gretty 会自动拉取对应的 gretty-runner 运行器，并强制锁定配套的容器依赖版本，无需你手动引入任何 Jetty/Tomcat 依赖。

方法二：在 gradle.properties 中精确覆盖版本号

如果内置的版本号不满足需求，你可以在项目的gradle.properties中直接覆盖。Gretty 在插件初始化时会优先读取你定义的属性（参见libs/gretty/src/main/groovy/org/akhikhl/gretty/GrettyPlugin.groovy中的apply逻辑）。

以项目根目录gradle.properties中的默认值为参考，覆盖方式如下：

jetty7Version=7.6.21.v20160908 jetty7ServletApiVersion=2.5 jetty8Version=8.1.14.v20131031 jetty8ServletApiVersion=3.0.1 jetty9Version=9.2.22.v20170606 jetty93Version=9.3.20.v20170531 jetty94Version=9.4.6.v20170531 jetty9ServletApiVersion=3.1.0 tomcat7Version=7.0.78 tomcat7ServletApiVersion=3.0.1 tomcat8Version=8.0.44 tomcat8ServletApiVersion=3.1.0

属性名规律一目了然：容器名 + Version控制容器本体，容器名 + ServletApiVersion控制配套的 Servlet API。所有以jetty、tomcat开头的版本号都能这样覆盖。

Servlet API 版本覆盖的注意事项

覆盖 Servlet API 是踩坑重灾区，牢记以下三点可以少走弯路：

1. 版本必须互相兼容。例如jetty7对应 Servlet 2.5、jetty8/tomcat7对应 Servlet 3.0.1、jetty9/tomcat8对应 Servlet 3.1，不要强行组合。
2. Gretty 会自动 force 依赖。在ServletContainerConfig.groovy中，每个容器配置都通过resolutionStrategy { force ... }锁定容器依赖，即使项目里有其他传递依赖，也不会把版本带偏。
3. 编译期与运行期保持一致。Gretty 通过grettyProvidedCompile配置提供 Servlet API 依赖（javax.servlet:javax.servlet-api），确保你编译时用的 API 版本和运行时容器提供的完全一致，避免NoSuchMethodError。

常见问题排查

• 提示 "Unsupported servlet container"：检查servletContainer拼写，只支持上文表格中的 7 个取值。
• 切换容器后项目启动报 ClassNotFoundException：先清理构建产物（gradle clean），再确认gradle.properties中覆盖的版本号真实存在。
• Java 8 以下无法使用 jetty9.3/9.4：换回jetty9或升级 JDK。

写在最后

掌握 Gretty 版本覆盖，本质就是记住两个动作：切换servletContainer和覆盖gradle.properties中的版本属性。前者决定"用哪个容器"，后者决定"容器多精确的版本"。配合 Gretty 自动的依赖锁定机制，你完全可以把容器差异交给 Gretty 管理，专心写业务代码。

如果你想深入源码理解版本锁定的实现细节，可以重点阅读libs/gretty/src/main/groovy/org/akhikhl/gretty/ServletContainerConfig.groovy与GrettyPlugin.groovy两个文件，逻辑非常清晰。

【免费下载链接】grettyAdvanced gradle plugin for running web-apps on jetty and tomcat.项目地址: https://gitcode.com/gh_mirrors/gr/gretty