最近又有人问我，Gradle到底怎么创建一个web工程。他们有的是从Maven转过来的，有的干脆是第一次接触构建工具，照着网上的教程敲了一遍，项目能跑起来，但换个环境又抓瞎。这篇我把Gradle入门里最常见的需求——创建一个普通的web工程——完整走一遍，包括环境准备、两种构建姿势、打包部署和几个高频坑。如果你已经能把Java项目跑起来，但还没系统玩过Gradle，这篇应该刚好能帮你把项目搭起来，并且知道每一步为什么这么做。
1. 构建工具怎么选：Gradle凭什么是web工程的合适选项
1.1 从Ant到Maven再到Gradle，变化本质是什么
每个时代都有自己的构建工具代表。Ant时代是“配置即代码”，写build.xml就像写一份详细的操作手册，先创建目录、再编译、再打包，每一步都得自己描述清楚，换个项目结构就得重写一遍。Maven时代变成了“约定优于配置”，src/main/java放源码、src/main/resources放资源，目录结构定死了，一条mvn package命令走完整个生命周期，省心很多。Gradle在这里是个折中：保留了Maven的目录约定，但把配置方式改成编程式，用Groovy或Kotlin写逻辑，task之间可以自由编排、互相依赖。
我第一次接触Gradle时，感觉它像一个“会记事的装修队长”。它知道哪些材料已经搬过、这次只需要补什么，而不是像Maven那样每次从头把流程重跑一遍。这个记忆能力来自增量构建机制：如果task的输入输出没有变化，Gradle会把该task标记为UP-TO-DATE，直接跳过执行。配合常驻后台的守护进程，构建体验比Maven命令行那一套快不少，尤其在多模块项目里，差别能到几倍。
1.2 做web工程，Gradle到底赢在哪
web工程和普通Java工程不一样的地方在于，它除了源码编译，还涉及资源过滤、静态文件处理、war包或可执行jar的打包、容器部署等多个环节。Gradle对这些场景支持得很顺手：插件化设计让war、application、spring-boot插件各司其职；依赖管理直接兼容Maven仓库，坐标风格一致，从Maven迁移过来不用改依赖认知；多模块工程支持成熟，子项目可以单独配置、单独构建；生命周期还可以任意定制，哪个task想插在build之前执行，写几行配置就行。
但这不是说Maven不行。如果团队里人人都是Maven老手，项目也是常规单模块，强行换Gradle没有太大必要。我的判断标准是：新项目可以直接用Gradle起步，老项目看团队接受程度。项目一旦开始膨胀，构建时间久到让人抓狂，或者要深度定制构建环节——比如在打包前根据环境动态替换配置、生成版本文件——Gradle的收益就很明显。web工程现在普遍要接CI流水线，本地构建快、增量能力强，直接影响整个团队的开发节奏。
2. 敲代码之前：把Gradle环境收拾利索
2.1 JDK和Gradle版本要匹配
很多人第一步就栽在版本上。Gradle版本和JDK版本不对应，启动就报Unsupported class file major version之类的问题。大致上说，Gradle 8.x对JDK 11到21都支持得比较好，Gradle 9.x要求JDK 17起步。最稳妥的方案是：先确定目标框架需要哪个JDK版本，再反推Gradle版本，而不是装个最新的Gradle硬上。
我用了很长一段时间的Gradle 8.5配合JDK 17，兼容性好，也覆盖了绝大多数web工程需求。如果你只是入门，选一个保守的组合比追新重要得多。版本这东西，满足项目需求就好，没必要每次都追最新的。这里给一个简单对照参考：
| Gradle版本 | 推荐JDK |
|---|---|
| 7.x | JDK 8、11、17 |
| 8.x | JDK 11、17、21 |
| 9.x | JDK 17及以上 |
2.2 安装Gradle与IDE配置
安装方式有很多种，Windows上直接下载zip包解压最省事，类Unix系统可以用SDKMAN这类工具装，也可以手动解压包。关键是配置环境变量：GRADLE_HOME指向解压目录，PATH里加上$GRADLE_HOME/bin，然后在命令行敲一个gradle -v确认版本输出正常。如果JAVA_HOME没配好，这里就会直接报错，所以JDK环境是第一步。
IDE方面，现在主流IDE基本都内置Gradle支持。以IDEA为例，导入项目时选到build.gradle文件，它会自动识别成Gradle项目；导入之后如果某些task没出现，去设置里检查Gradle的user home和JVM参数。Eclipse需要单独装buildship插件，我平时用得少，但这两年插件成熟不少，Eclipse用户直接搜buildship装上就能用。
配置Gradle时有个容易忽略的地方：项目根目录的gradle.properties可以设置全局JVM参数。常见配置是：
org.gradle.jvmargs=-Xmx2g -XX:+MaxMetaspaceSize=512m org.gradle.daemon=true org.gradle.caching=true前两行决定构建进程能用多少内存，后两行开启常驻进程和构建缓存。机器内存够的话，这几个配置对构建速度影响很明显。IDEA里默认的Gradle user home一般放在用户目录的.gradle下面，如果系统盘空间紧张，也可以改到其他磁盘，避免缓存膨胀后把C盘塞满。
2.3 用Wrapper固定构建版本
接手别人的Gradle项目，最烦的不是代码，而是“我电脑上能构建，你电脑上报错”。很多新手看不懂项目根目录下的gradlew和gradlew.bat是什么，它们是Gradle Wrapper的启动脚本，作用就是让所有人在同一个Gradle版本下工作。
打开gradle/wrapper/gradle-wrapper.properties，里面有个distributionUrl字段，写着要下载的Gradle版本。相比手动安装全局Gradle，我更推荐项目统一用gradlew命令，这样本地环境和CI用的版本一致，不会出现版本差异带来的灵异事件。刚入门的时候就在项目里养成用gradlew的习惯，后面能省掉大量麻烦。第一次执行gradlew时，它会自动下载对应版本，下载一次之后就有缓存了。
3. 创建web工程的两种姿势，build.gradle逐个拆
3.1 姿势一：传统Servlet工程，war包走容器
先说web工程最经典的形态：打一个war包，丢到Tomcat或Jetty的webapps目录里跑。Gradle里做这件事的核心是war插件。一个最基本的build.gradle长这样：
plugins { id 'java' id 'war' } group = 'com.example' version = '1.0.0' repositories { mavenCentral() } dependencies { // Servlet API由容器提供，编译时需要，运行时不需要打进包里 providedCompile 'javax.servlet:javax.servlet-api:4.0.1' } war { archiveFileName = 'demo-web.war' }这里面有三个关键点。plugins块引入java和war插件，war插件会扩展java插件的功能，并且自动识别src/main/webapp目录。providedCompile表示这个依赖只在编译期使用，因为Servlet API在Tomcat里已经存在，打war包时不能重复放进去，否则运行时容易类冲突。repositories里的mavenCentral()表示从Maven中央仓库拉依赖，和Maven的中央仓库是同一个。
对应的目录结构长这样：
src/main/java src/main/resources src/main/webappwebapp目录下面可以放静态资源和WEB-INF，老式项目会有web.xml，Servlet 3.0以上也可以不写web.xml直接用注解。war插件默认不认识webapp目录，所以如果你发现新建的目录没有高亮图标，多半是war插件没引入成功。
写个最简单的Servlet验证一下：
@WebServlet("/hello") public class HelloServlet extends HttpServlet { @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { resp.getWriter().write("Hello Gradle Web"); } }构建命令是gradle clean build，产物在build/libs/demo-web.war。这里要提醒一件事：war包里用javax.servlet还是jakarta.servlet，取决于你的Servlet容器版本。Tomcat 10以上用的是jakarta命名空间，如果还是用javax.servlet-api的包打进去，部署时基本都会报ClassNotFoundException，这是近两年war项目迁移最常见的坑。
3.2 姿势二：Spring Boot内嵌容器，可执行jar一步到位
现在很多web工程不追求war包了，直接用Spring Boot打成可执行jar，里面内嵌Tomcat。构建脚本长这样：
plugins { id 'java' id 'org.springframework.boot' version '2.7.18' id 'io.spring.dependency-management' version '1.0.15.RELEASE' } group = 'com.example' version = '1.0.0' java { sourceCompatibility = '11' } repositories { mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation 'org.springframework.boot:spring-boot-starter-test' }这段脚本引了spring-boot插件和dependency-management插件，后者会从Spring Boot的BOM自动决定依赖版本，所以starter-web这一行不需要写版本号。运行时直接java -jar xxx.jar，Spring Boot会自动启动内嵌的Tomcat，不需要外部容器。Spring Boot 3.x要求JDK 17以上，如果你开的是新环境，可以直接上3.x；但很多老项目还在用2.x，这个根据团队基线来就好。
很多新手会问：Spring Boot插件和war插件能不能一起用？可以，但一般没必要。两个都引入后，bootWar任务会接管war打包。实际项目里我通常只用其一：要么纯war交给外部容器，要么纯jar自己跑。混着用容易搞混部署方式，运维脚本也不好统一。
3.3 两种姿势怎么选，一张表说清楚
| 对比点 | war包方案 | Spring Boot可执行jar |
|---|---|---|
| 部署方式 | 需要外部Tomcat | java -jar直接启动 |
| 版本命名空间 | 涉及javax/jakarta问题 | 框架统一处理 |
| 内存占用 | 容器固定占一块 | 单进程内嵌 |
| 热部署 | 容器自带热部署 | devtools等方式实现 |
| 适合场景 | 运维规范严格的传统环境 | 云原生、容器化、微服务 |
选型建议很简单：新项目、云环境、微服务起步，直接选Spring Boot jar，部署简单还能直接扔进Docker镜像。如果运维要求固定Tomcat版本、手工管理webapps目录，war还是更稳妥的选项。这个决定影响后续整个发布流程，早定早省心。
3.4 仓库、依赖scope和容易忽略的配置细节
依赖配置名称看着容易头晕，实际上逻辑很简单。implementation是编译和运行时都需要，但不把依赖传递给别人；compileOnly是只在编译期用；runtimeOnly是只在运行期用；providedCompile是编译期有、不参与打包。整理一张表：
| 配置名 | 作用 | 典型场景 |
|---|---|---|
| implementation | 编译和运行时都参与，不传导给下游 | 常规业务依赖 |
| compileOnly | 只在编译期存在 | 注解处理器、Servlet API |
| runtimeOnly | 只在运行期存在 | JDBC驱动 |
| providedCompile | 编译期有，不打包 | 传统war里的servlet-api |
| testImplementation | 只在测试代码编译和运行 | 测试框架 |
repositories里的配置也有讲究。mavenCentral()是默认中央仓库，mavenLocal()会优先从本地仓库找，适合开发和CI共用同一台机器的场景。如果你配置了公司私服或者公共镜像，放在mavenCentral()前面会更快。多模块工程的话，还要在settings.gradle里写上include，让Gradle知道子模块有哪些，否则子模块build.gradle会被完全忽略。
还有一个小配置容易被忽略：源码编码。Windows环境下如果没指定UTF-8，带中文的源码编译时会出现乱码。在build.gradle里加上：
compileJava.options.encoding = 'UTF-8' compileTestJava.options.encoding = 'UTF-8'这两个配置一劳永逸，最好一开始就写上。
4. 实操一把梭：初始化、构建、部署
4.1 用gradle init快速创建项目骨架
在空目录执行gradle init，会问你想要生成什么类型的项目，选application或library，再选实现语言、DSL类型、构建脚本文件名等。生成完成后，目录里自动带着wrapper，新项目马上就能用./gradlew，不需要再手动下载全局Gradle。这里有个细节：gradle init生成的骨架是纯Java项目，不是web项目，所以我们之后还要自己加入war或spring-boot插件。
如果嫌交互式命令麻烦，也可以手工创建目录和文件。手工创建时记住三个约定：java源码放src/main/java，资源放src/main/resources，测试源码放src/test/java。Gradle和Maven在这点上几乎一致，熟悉Maven的人切换过来几乎零成本。web目录额外加一个src/main/webapp，然后引入war插件即可。
4.2 构建命令与任务生命周期的理解
Gradle里的任务像一张有依赖关系的网。敲gradle build，它自动先跑compileJava、processResources、classes、test等任务，每个任务都有明确的输入输出。想看到完整任务列表，可以跑gradle tasks --all。常见命令有这些：
gradle clean gradle build gradle bootRun gradle dependencies gradle dependencyInsight --dependency <依赖名> --configuration compileClasspathclean是删掉build目录，build是编译、测试、打包一气呵成，bootRun是Spring Boot项目直接起本地服务。dependencies可以打印完整依赖树，查看某个依赖通过哪条传递链路进来，用dependencyInsight查内幕，比肉眼看pom.xml靠谱得多。
4.3 打包产物与Tomcat/内嵌容器部署
war方案打包出来在build/libs下，文件名受war { archiveFileName }配置控制。部署时直接复制war到Tomcat的webapps目录，等Tomcat自动解压即可。注意war文件名决定了访问的上下文路径，如果你文件名是demo-web.war，访问路径一般是/demo-web/hello，不能随便改文件名。
Spring Boot jar方案更简单：
java -jar build/libs/demo-web-1.0.0.jar需要指定端口时可以用命令行参数：
java -jar build/libs/demo-web-1.0.0.jar --server.port=8081实际操作里有个小技巧可以分享一下：jar包如果带了版本号，自动发布脚本里文件名就得跟着版本变。所以我个人建议把archiveFileName固定成一个不带版本号的名字，比如demo-web.jar，这样Dockerfile、发布脚本不用每次改文件名。运维同事看到这种配置，普遍觉得省心不少。
4.4 顺带聊聊多模块web工程的入门认知
单模块工程看上面内容已经够用了，但web工程发展到后期，大概率会拆成api模块、service模块、dao模块。Gradle多模块配置很简单，把子模块写在settings.gradle里：
rootProject.name = 'demo-parent' include 'demo-core' include 'demo-web'根工程只放公共配置，子模块用各自的build.gradle独立控制。这时候Gradle的task图机制就有明显优势了，可以只构建其中某个子模块：
./gradlew :demo-web:build多模块并行构建的时候，Gradle比Maven更擅长利用现代机器的多核能力，构建速度差距会进一步拉大。如果你迟早要面对大工程，Gradle的这条路值得一开始就了解。
5. 高频问题排查，都是我实际踩过的坑
5.1 依赖下载永远没动静，看这里
新项目第一次构建时，Gradle要拉一堆依赖，网络不好时很容易卡在读条状态。解决思路是换镜像仓库或者配置公司私服。把repositories改成：
repositories { maven { url 'https://你的镜像地址/repository/public' } mavenCentral() }镜像也得选延迟低的，否则整条依赖链都会拖慢。还有一个小细节，Gradle发行版本身也是从远程下载的，如果卡在Downloading那一步，可以把gradle-wrapper.properties里的distributionUrl指到下载快的地址。首次构建多等几分钟很正常，但一直失败就要检查是磁盘空间不够、网络被拦截还是依赖坐标写错。本地构建缓存目录可以先用gradle clean清理干净再试，避免缓存里的损坏文件干扰。
5.2 版本冲突怎么查，比肉眼看强多了
Spring Boot的BOM已经帮你锁定了大部分依赖版本，但如果继续在dependencies里显式声明另一个版本，就可能出现两个版本同时存在的局面。排查冲突最常用的命令是：
./gradlew dependencyInsight --dependency jackson-databind --configuration compileClasspath这条命令会告诉你某个库为什么会被选中、哪个库间接依赖了它、最终版本被谁覆盖。如果确实要强制排除传递依赖，可以在dependencies里写exclude，但要小心，排掉一个依赖之后一定要手动补上正确版本，否则运行时会报NoClassDefFoundError。我在项目里见过好几次这种事故：排除依赖忘了补版本，启动直接崩。
5.3 热部署失效，先别怪devtools
Spring Boot开发者用spring-boot-devtools做热更新，经常遇到改代码后页面不换新。多数时候不是devtools失效，而是IDE没有把更新后的类输出到Gradle的build目录，或者构建缓存没失效。先跑一次clean，再去IDE里打开自动编译，看看能否解决。如果用的是外部Tomcat的war模式，改完代码总不能一直重启容器，可以引入热加载工具，或者干脆在开发环境切到Spring Boot jar模式，本地用bootRun跑，配合devtools会舒服很多。
5.4 Gradle常见错误速查表
| 报错信息 | 原因 | 解决思路 |
|---|---|---|
| Could not find method implementation() | Gradle版本太老，不支持新配置名 | 升级Gradle，或把implementation改回compile |
| Unsupported class file major version | JDK版本和Gradle不兼容 | 查Gradle兼容矩阵，换JDK或换Gradle |
| Could not resolve all dependencies | 依赖坐标写错或仓库不可达 | 核对坐标，检查镜像和私服配置 |
| No such property: archiveName | 新版本Gradle改了war任务属性 | 改用archiveFileName |
| java.lang.OutOfMemoryError: Metaspace | 构建进程内存不够 | 在gradle.properties调大org.gradle.jvmargs |
| Task 'bootRun' not found | 没引入Spring Boot插件 | 检查plugins块是否正确 |
| 部署到Tomcat 10+报ClassNotFoundException | Servlet API命名空间不匹配 | 换成jakarta.servlet-api，或降低容器版本 |
这张表里的问题我基本都遇到过，有些是老项目升级Gradle时冒出来的，有些是环境不一致导致的。新手最容易卡在第一个和第二个，原因几乎都是安装Gradle时没注意版本新旧，或者IDE内置的Gradle版本和命令行版本不一致。遇到问题先看清是哪个环境在报错，再对症下药。
5.5 构建缓存和.gradle目录越来越大的处理
Gradle会在用户目录的.gradle下存一堆缓存，版本迭代多了以后，这个目录可能膨胀到几个G。依赖缓存要保留，不需要每次重新拉；但构建缓存和旧版本wrapper distribution是可以清理的。你也可以设置GRADLE_USER_HOME指向其他磁盘位置，比如D盘，这样系统盘空间不会告急。
构建缓存失效的原因也比较多，文件时间戳变化、JVM参数变化、task输入输出定义不清晰都会导致缓存无效。最无奈但管用的方法就是gradle clean，删掉build目录再来一次。如果你的项目里写了自定义task，一定要把task的inputs和outputs声明清楚，否则Gradle会认为输入总是发生变化，缓存等同于废的。
我个人玩Gradle这几年，最大的体会是别一开始就陷进DSL和task定制的深水区，先把build.gradle最小配置跑通，亲眼看着一个web工程从代码变成war或jar、再到成功访问页面，就算真正入门了。后面再慢慢折腾多模块、自定义task、CI流水线，都会顺理成章。最后再分享一个小技巧：项目里一定要把wrapper相关文件提交到版本库，这样无论谁拉下代码，构建版本都保持一致，能少吵很多架。
