Spring Boot开发中视图渲染返回404错误是非常常见的问题，出现这类问题通常和配置、路径映射、文件位置等多个环节相关，需要逐一排查定位根因。
常见原因分析
1. 视图解析器配置错误
如果使用的是Thymeleaf等模板引擎，没有正确配置视图解析器的前缀和后缀，会导致框架找不到对应的模板文件。比如Thymeleaf默认的前缀是classpath:/templates/，后缀是.html，如果手动修改了配置但路径不正确，就会触发404。
2. 控制器请求映射不匹配
控制器的@RequestMapping注解配置的路径和实际请求的URL不一致，或者方法返回的逻辑视图名和模板文件名不匹配，都会导致视图渲染失败。比如控制器返回index，但模板文件是home.html，就会出现404。
3. 模板文件位置错误
Spring Boot默认的模板文件存放路径是src/main/resources/templates/，如果开发者把模板文件放到了其他目录，比如static目录或者自定义的非默认路径，又没有额外配置，框架就无法找到对应的模板文件。
4. 静态资源访问冲突
如果请求的URL被静态资源处理器优先匹配，而静态资源目录下没有对应的文件，也会返回404。比如请求/index.html，而static目录下没有这个文件，同时控制器也没有映射/index路径，就会出现问题。
对应解决方案
1. 检查视图解析器配置
如果是使用Thymeleaf，首先确认依赖是否正确引入，然后在application.properties或者application.yml中检查配置：
# Thymeleaf配置 spring.thymeleaf.prefix=classpath:/templates/ spring.thymeleaf.suffix=.html spring.thymeleaf.mode=HTML spring.thymeleaf.encoding=UTF-8 spring.thymeleaf.cache=false
如果是自定义视图解析器，需要确认前缀和后缀的路径是否正确，没有多余的斜杠或者拼写错误。
2. 核对控制器映射和返回视图名
检查控制器的请求路径和返回的逻辑视图名是否正确，以下是一个正确的示例：
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class IndexController {
// 请求路径是/index
@GetMapping("/index")
public String index() {
// 返回的逻辑视图名是index，对应templates/index.html
return "index";
}
}
如果返回的逻辑视图名带路径，比如return "user/index"，那么对应的模板文件应该是templates/user/index.html。
3. 确认模板文件存放位置
把模板文件放到默认的src/main/resources/templates/目录下，如果是自定义目录，需要在配置中添加对应的前缀：
# 自定义模板路径为classpath:/my-templates/ spring.thymeleaf.prefix=classpath:/my-templates/
同时确认文件名和返回的逻辑视图名完全一致，包括大小写，因为部分操作系统对文件名大小写敏感。
4. 处理静态资源冲突
如果需要访问静态资源，把静态文件放到src/main/resources/static/、src/main/resources/public/等默认静态资源目录下。如果同时存在控制器映射和静态资源文件，需要注意请求路径的优先级，避免冲突。如果需要排除静态资源对控制器路径的干扰，可以在配置中添加静态资源处理规则：
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 配置静态资源路径，排除/static/**路径的控制器映射
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
}
}
排查小技巧
可以在控制器方法中打印日志，确认方法是否被调用，如果方法没有被调用，说明是请求路径映射的问题；如果方法被调用但返回404，说明是视图解析或者模板文件的问题。也可以开启Spring Boot的调试日志，查看视图解析器的具体查找过程：
# 开启Spring Web的调试日志 logging.level.org.springframework.web=DEBUG
通过日志可以清楚看到框架查找模板文件的路径，快速定位问题所在。
Spring_Boot视图渲染404错误Thymeleaf修改时间：2026-07-06 14:36:26