Spring Boot中dispatcherServlet无法解析index视图的排查与创建指南

一、先搞定「无法解析index视图」的报错 #

你说文件夹结构正常但还是踩坑，那咱们从几个高频排查点入手：

1. 检查依赖是否配齐
   要是用Spring Boot MVC最常用的Thymeleaf模板引擎，务必确保pom.xml（Maven）或build.gradle（Gradle）里加对了依赖：
   Maven示例：

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-thymeleaf</artifactId>
   </dependency>
   

   Gradle示例：

   implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
   

   要是你用JSP的话，得额外做一堆配置，而且Spring Boot现在不推荐用JSP（比如打包成jar包后容易找不到视图），建议直接换Thymeleaf。

2. 确认视图文件的位置和后缀
   Thymeleaf的视图文件默认要放在src/main/resources/templates/目录下，文件名得是index.html（别写成index.jsp或者其他后缀）。要是你把视图文件丢去static文件夹了也不行——static是放css、js这类静态资源的，不是视图的地盘。

3. 检查控制器的注解和返回值
   新手最容易犯的错：把@Controller写成@RestController！后者会把方法返回值当成JSON字符串直接返回，根本不会走视图解析器。正确的控制器写法应该是这样：

   @Controller
   public class HomeController {
       @GetMapping("/")
       public String home() {
           return "index"; // 这里直接写文件名，不用加.html后缀
       }
   }
   

4. 核对application配置里的视图解析器设置
   要是你乱改了默认配置，也会导致找不到视图。打开application.properties，检查这两项：

   # 默认就是/templates/，别瞎改
   spring.thymeleaf.prefix=classpath:/templates/
   # 默认是.html，也别动
   spring.thymeleaf.suffix=.html
   

二、正确创建Spring Boot MVC项目的步骤 #

我平时都是用Spring Initializr创建，步骤超简单：

• 直接在IDEA里打开「New Project」选择Spring Initializr（不用开网页），选好Maven/Gradle、Java版本（比如17）。
• 勾选Spring Web（MVC的基础依赖）和Thymeleaf（视图引擎）这两个核心依赖。
• 生成项目后导入到IDE里就能直接用了。

三、标准的Spring Boot MVC目录结构 #

给你列个最规范的结构，照着来绝对不会出问题：

your-project-name/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── demo/
│   │   │               ├── DemoApplication.java  # 主启动类，必须在最外层包！
│   │   │               ├── controller/           # 控制器层，放所有@Controller类
│   │   │               │   └── HomeController.java
│   │   │               ├── service/              # 业务逻辑层
│   │   │               │   └── UserService.java
│   │   │               └── repository/           # 数据访问层（和数据库交互）
│   │   │                   └── UserRepository.java
│   │   └── resources/
│   │       ├── templates/                       # Thymeleaf视图文件存放地
│   │       │   └── index.html
│   │       ├── static/                          # 静态资源：css、js、图片等
│   │       │   ├── css/
│   │       │   │   └── style.css
│   │       │   └── js/
│   │       │       └── app.js
│   │       └── application.properties           # 全局配置文件
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── demo/
│                       └── DemoApplicationTests.java
└── pom.xml  # Maven配置（Gradle项目是build.gradle）

重点提醒：主启动类DemoApplication.java必须放在最外层包，这样Spring才能自动扫描到下面的controller、service等组件，不然控制器会被漏掉，也可能间接导致视图解析失败。

最后再排查下你可能的操作失误 #

• 是不是把@Controller写成@RestController了？
• 视图文件是不是放错目录（比如丢去static了）？
• 是不是只加了Spring Web依赖，没加Thymeleaf？

把上面这些点都过一遍，大概率能解决问题。要是还不行，可以把控制器代码和目录结构贴出来，咱们再细查。

内容的提问来源于stack exchange，提问作者ebinezer p