Spring Boot+Maven项目控制器无法返回HTML页面求助

• 检查静态资源/模板文件位置

  • 若使用Thymeleaf模板引擎，index.html必须放在src/main/resources/templates/目录下；纯静态HTML则放在src/main/resources/static/、public/或resources/目录中。
  • 核对文件结构，避免将HTML文件嵌套在多余的子目录里，确保路径层级正确。

• 校验pom.xml依赖配置

  • 使用Thymeleaf时，必须引入对应starter依赖，缺失会导致模板无法解析：

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

  • 仅用静态HTML时，确保spring-boot-starter-web依赖已正确引入，无需额外模板依赖。

• 检查控制器代码正确性

  • 控制器类必须标注@Controller（不能用@RestController，后者会直接返回文本/JSON，不解析视图）。
  • 方法映射路径与返回值需匹配，示例：

    @Controller
    public class HomePageController {
        @GetMapping("/")
        public String index() {
            return "index"; // Thymeleaf模板模式下返回模板名，不带后缀；静态HTML可直接返回"index.html"
        }
    
        @GetMapping("/home")
        public String home() {
            return "index";
        }
    }
    

  • 可直接访问localhost:8080/index.html测试静态资源是否能加载，快速排查控制器本身的问题。

• 确认主类扫描范围

  • @SpringBootApplication注解默认扫描主类所在包及其子包，确保控制器类在该扫描范围内，避免因包结构错误导致控制器未被加载。
  • 不要随意添加@ComponentScan注解，防止缩小扫描范围。

• 检查配置文件参数

  • Thymeleaf模式下，确认配置未禁用模板解析：

    spring.thymeleaf.enabled=true
    spring.thymeleaf.prefix=classpath:/templates/
    spring.thymeleaf.suffix=.html
    

  • 静态资源模式下，确认静态资源路径配置正确：

    spring.web.resources.static-locations=classpath:/static/,classpath:/public/,classpath:/resources/
    

• 清理缓存并重启

  • 执行mvn clean install清理编译缓存后，重新启动Spring Boot应用。
  • 浏览器按Ctrl+F5强制刷新，避免缓存旧的错误页面。

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