作为一名后端开发者，我还记得第一次搭SpringBoot-Web项目时的场景：对着网上的教程复制Maven依赖，结果要么版本冲突导致项目启动失败，要么静态资源访问报404，折腾了大半天才勉强跑起来。

后来做的项目多了才发现，搭建SpringBoot-Web项目根本不用这么费劲——只要搞懂Maven的依赖管理逻辑，掌握核心配置要点，30分钟就能从零搭建一个可直接上线的Web项目。

今天就结合我多年的实战经验，从环境准备、Maven项目创建、核心依赖配置、接口开发、静态资源处理到打包部署，把SpringBoot-Web项目的搭建流程讲透，还会附上新手最容易踩的坑和解决方案，让你少走弯路。

一、 环境准备：先把基础工具配齐

工欲善其事，必先利其器。搭建SpringBoot-Web项目前，必须先准备好这几个工具，版本搭配很重要，不然容易出兼容性问题。

工具	推荐版本	说明
JDK	8/17	SpringBoot 2.x推荐JDK8，3.x推荐JDK17（兼容更好）
Maven	3.6.x及以上	版本太低会不支持SpringBoot的依赖管理
IDE	IntelliJ IDEA/Eclipse	IDEA的Maven集成更友好，推荐新手使用
SpringBoot	3.2.x（稳定版）	选择官方稳定版，避免尝鲜新版本的坑

验证环境是否就绪：

1. 打开命令行，输入java -version，能看到JDK版本号；
2. 输入mvn -v，能看到Maven版本号和JDK关联信息。

二、 两种搭建方式：Maven手动创建 vs Spring Initializr快捷生成

搭建SpringBoot-Web项目有两种方式，一种是手动创建Maven项目+配置依赖，适合理解底层逻辑；另一种是用Spring Initializr一键生成，适合快速开发。我们两种都讲，按需选择。

方式1：手动创建Maven项目（吃透底层配置）

这种方式能让你彻底搞懂Maven和SpringBoot的依赖关系，新手建议先从这种方式入手。

步骤1：创建普通Maven项目

1. 打开IDEA，点击File → New → Project；
2. 选择Maven，取消勾选Create from archetype，点击Next；
3. 填写项目信息：
   • GroupId：公司/组织标识（比如com.example）
   • ArtifactId：项目名称（比如springboot-web-demo）
   • Version：版本号（比如1.0-SNAPSHOT）
4. 选择项目存储路径，点击Finish。

步骤2：配置Maven核心依赖（关键！）

打开项目根目录下的pom.xml，添加SpringBoot的父依赖和web启动器依赖——这是SpringBoot-Web项目的核心。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- SpringBoot父依赖：统一管理依赖版本，避免版本冲突 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>

    <!-- 项目基本信息 -->
    <groupId>com.example</groupId>
    <artifactId>springboot-web-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>springboot-web-demo</name>

    <!-- 核心依赖：spring-boot-starter-web -->
    <dependencies>
        <!-- Web启动器：内置Tomcat、SpringMVC、Jackson等核心组件 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 测试依赖：可选 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- 打包插件：将项目打包成可执行的jar包 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>3.2.0</version>
            </plugin>
        </plugins>
    </build>
</project>

重点解析：

• spring-boot-starter-parent：是SpringBoot的父POM，作用是统一管理依赖版本。比如我们引入spring-boot-starter-web时不用写版本号，就是因为父POM已经定义好了。
• spring-boot-starter-web：Web项目的核心启动器，内置了：
  • 嵌入式Tomcat服务器（不用手动配置Tomcat）；
  • SpringMVC核心组件（DispatcherServlet、控制器映射等）；
  • Jackson（处理JSON数据序列化/反序列化）。
• spring-boot-maven-plugin：打包插件，能将项目打包成可独立运行的jar包，直接通过java -jar命令启动。

步骤3：创建项目目录结构

SpringBoot项目有固定的目录规范，按照这个结构创建，能避免很多配置问题：

src/main/java/com/example/
├── SpringbootWebDemoApplication.java  // 启动类
├── controller/                         // 控制器层
├── service/                            // 业务逻辑层
└── mapper/                             // 数据访问层（可选）
src/main/resources/
├── application.properties              // 核心配置文件
├── static/                             // 静态资源目录（js、css、img）
└── templates/                          // 模板文件目录（thymeleaf、freemarker）

步骤4：编写启动类（项目入口）

在com.example包下创建启动类，这是SpringBoot项目的唯一入口，必须加@SpringBootApplication注解。

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// 核心注解：标记这是SpringBoot应用的启动类
@SpringBootApplication
public class SpringbootWebDemoApplication {
    public static void main(String[] args) {
        // 启动SpringBoot应用
        SpringApplication.run(SpringbootWebDemoApplication.class, args);
    }
}

方式2：Spring Initializr一键生成（快速开发）

如果觉得手动配置麻烦，可以用Spring官方提供的Initializr工具一键生成项目，适合实际开发。

步骤1：打开Spring Initializr官网

访问https://start.spring.io/，这是Spring官方的项目生成工具。

步骤2：配置项目信息

• Project：选择Maven Project；
• Language：选择Java；
• Spring Boot：选择3.2.0（稳定版）；
• Group、Artifact、Name：和手动创建时一致；
• Dependencies：添加Spring Web依赖。

步骤3：生成并导入项目

点击Generate按钮，下载项目压缩包，解压后用IDEA打开即可——项目的pom.xml、目录结构、启动类都已经自动生成好了。

三、 实战开发：写一个简单的Web接口

项目搭建好后，我们来写一个RESTful接口，测试项目是否能正常运行。

步骤1：编写控制器（Controller）

在controller包下创建HelloController：

package com.example.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// 核心注解：@RestController = @Controller + @ResponseBody
@RestController
public class HelloController {

    // 定义GET请求接口，路径为/hello
    @GetMapping("/hello")
    public String hello() {
        return "Hello SpringBoot-Web!";
    }

    // 带参数的GET接口，路径为/hello/{name}
    @GetMapping("/hello/{name}")
    public String helloWithName(@PathVariable String name) {
        return "Hello " + name + "!";
    }
}

注解解析：

• @RestController：组合注解，等价于@Controller + @ResponseBody，表示这个类是控制器，且返回值直接作为JSON/字符串响应，不用走视图解析器。
• @GetMapping("/hello")：映射GET请求，路径为/hello。

步骤2：配置核心参数（application.properties）

打开src/main/resources/application.properties，添加基础配置：

# 服务器端口（默认8080，避免冲突可修改）
server.port=8081

# 应用名称
spring.application.name=springboot-web-demo

# 静态资源路径（默认classpath:/static/）
spring.web.resources.static-locations=classpath:/static/

步骤3：启动项目并测试

1. 右键点击启动类SpringbootWebDemoApplication，选择Run；
2. 控制台看到如下日志，说明启动成功：

   Tomcat started on port 8081 (http) with context path ''
   Started SpringbootWebDemoApplication in 1.5 seconds (process running for 2.0)
   

3. 打开浏览器，访问http://localhost:8081/hello，页面显示Hello SpringBoot-Web!；
4. 访问http://localhost:8081/hello/Java，页面显示Hello Java!。

四、 进阶操作：打包部署+静态资源访问

搭建完项目，还要知道怎么打包部署，以及如何访问静态资源，这是实际开发中必须掌握的技能。

1. 打包成可执行Jar包

1. 打开IDEA的Terminal终端，输入命令：

   mvn clean package
   

2. 打包成功后，在项目的target目录下会生成一个springboot-web-demo-1.0-SNAPSHOT.jar文件；
3. 打开命令行，进入target目录，输入启动命令：

   java -jar springboot-web-demo-1.0-SNAPSHOT.jar
   

4. 同样可以访问http://localhost:8081/hello，说明打包部署成功。

2. 静态资源访问实战

SpringBoot默认会扫描classpath:/static/目录下的静态资源（js、css、img），我们来测试一下：

1. 在src/main/resources/static目录下创建index.html：

   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <title>SpringBoot静态资源</title>
   </head>
   <body>
       <h1>这是静态资源页面</h1>
   </body>
   </html>
   

2. 重启项目，访问http://localhost:8081/index.html，就能看到这个页面。

五、 高频踩坑指南：5个新手必遇问题及解决方案

我整理了搭建SpringBoot-Web项目时最容易踩的5个坑，结合实战经验给出修复方案。

坑1：项目启动失败，提示“端口被占用”

• 原因：server.port配置的端口被其他程序占用（比如默认的8080端口）；
• 解决方案：
  1. 在application.properties中修改端口：server.port=8082；
  2. 或者在命令行中杀死占用端口的进程（Windows用netstat -ano | findstr 8080，Linux用lsof -i:8080）。

坑2：依赖冲突，提示“ClassNotFoundException”

• 原因：手动添加的依赖版本和SpringBoot父POM的版本不一致；
• 解决方案：
  1. 尽量使用父POM管理的版本，不要手动指定依赖版本；
  2. 用Maven的dependency:tree命令查看依赖树，排除冲突的依赖：

     mvn dependency:tree
     

坑3：控制器返回404错误

• 原因：
  1. 启动类的包层级不对（比如启动类在com.example，控制器在com.test，导致扫描不到）；
  2. 注解写错（比如用了@Controller而不是@RestController，且没有加@ResponseBody）；
• 解决方案：
  1. 确保控制器在启动类的子包下，或者在启动类上添加@ComponentScan("com.test")指定扫描包；
  2. 正确使用@RestController注解。

坑4：静态资源访问404

• 原因：静态资源放错目录，或者修改了静态资源路径但配置错误；
• 解决方案：
  1. 默认将静态资源放在classpath:/static/目录下；
  2. 如果自定义路径，要在application.properties中配置spring.web.resources.static-locations。

坑5：打包后运行jar包提示“找不到主类”

• 原因：没有添加spring-boot-maven-plugin打包插件，或者插件版本和SpringBoot版本不一致；
• 解决方案：在pom.xml中添加正确的打包插件，版本和SpringBoot父依赖版本保持一致。

六、 总结与面试要点

用Maven搭建SpringBoot-Web项目的核心就是依赖配置+启动类+控制器开发，记住这几个关键点：

1. spring-boot-starter-parent是版本管理核心，spring-boot-starter-web是Web项目的基石；
2. @SpringBootApplication是启动类的核心注解，负责扫描组件和开启自动配置；
3. @RestController用于编写RESTful接口，返回JSON/字符串响应。

最后整理几个面试中常问的知识点：

1. spring-boot-starter-web包含哪些核心组件？（嵌入式Tomcat、SpringMVC、Jackson）
2. SpringBoot项目的启动流程是什么？（启动类main方法→SpringApplication.run()→加载自动配置类→启动Tomcat→扫描控制器）
3. 如何打包SpringBoot项目成可执行jar包？（用spring-boot-maven-plugin插件，执行mvn clean package）

希望这篇文章能帮你彻底搞定SpringBoot-Web项目的搭建，从手动配置到实战开发，再到避坑指南，一步到位。如果觉得有用，欢迎点赞、收藏、关注，后续会分享更多SpringBoot实战干货！