Spring Boot控制器404问题求助：本地新建项目异常，跨机器代码正常

1. 包扫描范围不匹配 #

Spring Boot默认只扫描主应用类所在包及其子包里的组件。如果本地新建项目时，@RestController所在的包不在主类的包层级下，控制器就不会被Spring容器加载，访问自然404。把代码移到主类里时，刚好在扫描范围内，所以能正常运行。而其他机器创建的项目大概率遵循了标准包结构（控制器放在主类的子包下），克隆到你本机后自然没问题。

2. Gradle构建配置存在差异 #

你用brew安装的Gradle，可能和其他机器的Gradle（比如官方下载版、IDE自带版）有配置差异，导致本地新建项目的构建脚本缺了关键配置：

• 检查build.gradle（或build.gradle.kts）里有没有正确引入Spring Boot插件和spring-boot-starter-web依赖，比如是否漏了id 'org.springframework.boot' version '3.0.3'这类插件声明。
• 本地新建项目时可能误删了依赖管理配置，导致Web组件没被正确打包到项目里。

3. M1架构的Gradle缓存异常 #

M1的ARM架构偶尔会导致Gradle缓存出现兼容性问题：

• 本地新建项目时，Gradle缓存的依赖可能存在架构不兼容的情况，间接导致Spring的组件扫描逻辑出错。
• 其他机器克隆过来的项目，依赖是在对应机器上构建缓存的，传到你本机后重新构建时缓存逻辑不同，反而能正常运行。
• 可以试试执行./gradlew clean build --no-build-cache清理缓存后重新构建项目。

4. Spring Boot CLI模板异常 #

brew安装的Spring Boot CLI生成的项目模板，可能和官方初始化器的模板有差异：

• 用spring init创建项目时，模板可能漏了@SpringBootApplication的默认扫描配置，或者默认包结构不符合规范。
• 其他机器如果是用官方初始化器创建的项目，模板更标准，所以克隆过来没问题。

5. IDE自动配置出错 #

如果用IDE打开本地新建项目，IDE的自动识别可能出问题：

• IDE没正确识别Spring Boot项目结构，导致组件扫描范围没被正确设置。
• 而克隆过来的项目是标准结构，IDE能正常识别，所以运行正常。

• 核对控制器的包路径：主应用类在com.example.demo的话，控制器要放在com.example.demo.controller这类子包下。
• 对比本地新建项目和克隆项目的build.gradle文件，找依赖、插件配置的差异。
• 执行./gradlew clean build --no-build-cache清理缓存后重新运行。
• 用官方初始化器生成一个标准Web项目，本地运行测试，排查是CLI模板问题还是本地环境问题。

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