1. 项目缘起为什么今天还要聊Spring Boot安装如果你在2021年10月28日搜索过“Spring Boot安装”那么你大概率是一位Java开发者正站在一个项目的起点或者准备将一个老项目迁移到更现代的框架上。时间来到现在Spring Boot的版本已经从当时的2.x系列演进到了3.x系列但一个核心事实没有改变Spring Boot依然是Java后端开发领域事实上的标准框架其“约定大于配置”的理念极大地简化了基于Spring的应用初始搭建和开发过程。今天重新审视这个话题并非简单地复述一遍安装步骤而是想结合这几年Spring Boot生态的变化、开发工具的演进以及我踩过的一些坑为你提供一份更贴近当前生产环境的“安装与使用”深度指南。你会发现正确的起点能让你在后续的开发、调试、部署中避开无数麻烦。网络上相关的热词如“knife4j文档请求异常 spring boot 3”、“eclipse在spring boot中搭配mybatis步骤”、“spring boot 2.4 nacos 配置”甚至安全相关的“cve-2025-22235”都从侧面印证了Spring Boot安装不仅仅是运行一个Hello World那么简单。它关乎你项目初始的依赖管理、构建工具选择、IDE配置、以及如何平滑地集成各种中间件和组件。一个草率的开始可能会在后续引入依赖冲突、配置无法读取、文档异常、甚至是安全漏洞。因此本文将超越简单的命令行操作深入到工具链选择、项目结构理解、以及如何为未来的扩展打下坚实基础。2. 环境奠基超越“有JDK就行”的准备工作很多教程会告诉你安装Spring Boot只需要JDK和Maven/Gradle。这没错但远远不够。为了获得顺畅的体验我们需要在动手之前建立一个更健壮的本地开发环境。2.1 JDK选型版本兼容性是第一道坎Spring Boot 3.x 要求 JDK 17 或更高版本而 Spring Boot 2.x 通常支持 JDK 8 及以上。如果你的项目没有历史包袱我强烈建议直接从 JDK 17 或最新的 LTS 版本如 JDK 21开始。这不仅是为了使用Spring Boot 3的新特性更是为了获得更好的性能、更现代的GC算法以及更丰富的语言特性。注意切勿在系统环境变量中同时配置多个JDK主目录这会导致JAVA_HOME指向混乱。推荐使用版本管理工具如jenvmacOS/Linux或通过IDE直接指定项目SDK。在Windows上可以手动切换环境变量但更推荐使用IDE的模块SDK配置功能。安装后在终端执行java -version和javac -version确保版本一致且符合预期。这里有一个常被忽略的细节检查默认的字符编码。在有些系统上控制台输出中文可能会是乱码。虽然Spring Boot应用通常以UTF-8运行但构建工具Maven/Gradle在执行时可能会继承系统编码。你可以在IDE的启动配置或Maven的MAVEN_OPTS环境变量中添加-Dfile.encodingUTF-8来一劳永逸地解决这个问题。2.2 构建工具抉择Maven还是Gradle这是经典的“萝卜青菜”问题但选择背后有逻辑。Apache Maven基于XML的声明式配置约定严格生命周期清晰。它的pom.xml文件结构固定依赖管理通过中央仓库协调对于大多数项目来说“够用且稳定”。如果你所在团队技术栈统一追求构建过程的可预测性和稳定性Maven是安全的选择。Spring官方初始器start.spring.io默认也提供Maven项目。Gradle基于Groovy或Kotlin DSL的脚本式配置极其灵活构建速度快尤其是增量构建。它允许你编写更简洁、更具表达力的构建脚本并且对于多模块项目、自定义构建任务的支持更强大。如果你需要复杂的构建流程或者团队熟悉脚本Gradle能带来更高的效率。我的建议是新手或团队项目求稳选Maven追求极致效率和灵活性且愿意学习DSL选Gradle。对于本文我将以Maven为主进行演示因为它的受众更广且原理相通。安装Maven后同样需要配置MAVEN_HOME并加入PATH通过mvn -v验证。2.3 IDE的选择与关键配置“eclipse在spring boot中搭配mybatis步骤”这个热词暗示了IDE配置的重要性。主流选择是IntelliJ IDEA旗舰版或社区版和Eclipse搭配Spring Tools Suite插件。IntelliJ IDEA对Spring Boot的支持是开箱即用的无论是代码提示、运行配置还是Actuator端点查看都集成得非常好。社区版对于普通的Spring Boot开发完全足够。Eclipse with STS这是一个完全免费且功能强大的组合。STS插件提供了专属的Spring Boot仪表板、属性文件提示、Bean可视化等高级功能。无论选择哪个请确保完成以下关键配置设置正确的JDK在IDE的全局设置或项目结构中指定使用我们之前安装的JDK版本。配置Maven在IDE的设置中指向本地安装的Maven和其settings.xml文件通常用于配置镜像仓库加速依赖下载。强烈建议将Maven仓库镜像改为国内源如阿里云镜像这能节省大量依赖下载时间。启用注解处理Spring Boot大量使用Lombok、MapStruct等注解处理器。在IDEA中需要在设置中勾选“Enable annotation processing”在Eclipse中可能需要安装Lombok插件并确保项目启用了注解处理。3. 项目创建三种方式与背后的考量创建Spring Boot项目有多种途径每种方式适合不同的场景。3.1 官方初始器start.spring.io最佳起点这是最推荐的方式尤其对于新手。访问 https://start.spring.io 你会看到一个直观的Web界面。你需要做出以下选择ProjectMaven Project 或 Gradle Project。LanguageJava默认、Kotlin 或 Groovy。Spring Boot选择最新的稳定版本如3.x.x。除非有明确兼容性要求否则不建议选择过旧的版本。Project MetadataGroup通常使用公司或组织域名的反写如com.example。Artifact项目名称也是最终生成jar包的名字如demo。Name、Description可自定义。Package name会自动根据Group和Artifact生成如com.example.demo。这里要注意这个包名将是你的主应用类SpringBootApplication标注的类的默认位置后续的组件扫描会基于此。PackagingJar默认或War。Spring Boot强烈推荐使用可执行Jar它内嵌了Web服务器如Tomcat无需额外部署到外部容器。只有当你需要将应用部署到传统的外部Tomcat等Servlet容器时才选择War。Java选择与你安装的JDK匹配的版本如17。Dependencies这是核心在这里添加你项目需要的起步依赖。例如要开发Web应用就添加Spring Web需要数据访问添加Spring Data JPA和对应的数据库驱动如MySQL Driver需要API文档可以添加SpringDoc OpenAPI这是Swagger/OpenAPI 3的现代实现比旧的springfox更推荐。点击“GENERATE”会下载一个压缩包。解压后用IDE打开这个文件夹注意是打开文件夹或作为Maven项目导入而不是直接打开其中的pom.xml一个结构完整、依赖就绪的Spring Boot项目就创建好了。3.2 通过IDE直接创建无缝集成IntelliJ IDEA和EclipseSTS都内置了从start.spring.io创建项目的功能。在IDEA中选择“New Project” - “Spring Initializr”在Eclipse中通过“File” - “New” - “Spring Starter Project”。这种方式的好处是项目创建后直接就在IDE的工作空间中无需额外导入步骤。界面和选项与Web版初始器基本一致。3.3 手动搭建理解骨架的每个部分对于学习或定制化要求极高的项目你可以从一个空的Maven项目开始手动构建。这能让你深刻理解pom.xml中的每个部分。创建一个标准的Maven项目。在pom.xml中设置parent为spring-boot-starter-parent。这个父POM管理了大量依赖的默认版本提供了统一的配置。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version !-- 使用最新稳定版 -- relativePath/ !-- 从仓库查找不继承本地 -- /parent添加你需要的“starter”依赖。例如添加Web支持dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 其他依赖... -- /dependencies添加Spring Boot Maven插件用于打包和运行。build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build创建主应用类在src/main/java下你的包路径里创建一个类用SpringBootApplication注解并包含一个标准的main方法。这种方式让你对项目的控制力最强但需要对Maven和Spring Boot的依赖管理有较好的理解。4. 核心结构解析与第一个应用解压或创建项目后我们来看看标准的Spring Boot项目结构并运行第一个程序。4.1 项目目录树解读demo/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/ │ │ │ └── example/ │ │ │ └── demo/ │ │ │ └── DemoApplication.java # 主应用入口 │ │ └── resources/ │ │ ├── static/ # 存放静态资源CSS, JS, 图片 │ │ ├── templates/ # 存放模板文件Thymeleaf, FreeMarker │ │ └── application.properties # 主配置文件 │ └── test/ # 测试代码目录 └── pom.xml # Maven项目对象模型文件DemoApplication.java这是应用的入口。SpringBootApplication是一个复合注解它包含了SpringBootConfiguration标记为配置类、EnableAutoConfiguration启用自动配置和ComponentScan组件扫描。main方法中通过SpringApplication.run()来启动应用。application.propertiesSpring Boot的核心配置文件。几乎所有框架的配置都可以在这里进行覆盖或定制。也支持YAML格式application.yml它层次更清晰。static和templates遵循Spring MVC的静态资源映射和视图解析约定。4.2 编写一个简单的REST接口让我们在主类同级或子包下创建一个HelloController。package com.example.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController // 等同于 Controller ResponseBody直接返回JSON/XML等数据 public class HelloController { GetMapping(/hello) public String sayHello(RequestParam(value name, defaultValue World) String name) { return Hello, name !; } }4.3 运行与测试你有多种方式运行这个应用IDE中直接运行在IDE中找到主类DemoApplication右键点击“Run”。这是最常用的开发期方式。使用Maven插件在项目根目录下打开终端执行mvn spring-boot:run。这会利用spring-boot-maven-plugin来启动应用。打包后运行执行mvn clean package会在target目录下生成一个可执行的Jar文件如demo-0.0.1-SNAPSHOT.jar。然后通过java -jar target/demo-0.0.1-SNAPSHOT.jar运行。应用启动后控制台会打印出大量的日志其中关键信息包括内嵌的Tomcat或其他服务器启动的端口默认8080。Spring Boot的Banner可以自定义或关闭。自动配置报告在日志级别为DEBUG时可见。打开浏览器访问http://localhost:8080/hello你会看到“Hello, World!”。访问http://localhost:8080/hello?nameSpringBoot你会看到“Hello, SpringBoot!”。5. 深度配置application.properties/yml的学问配置文件是Spring Boot灵活性的体现。默认的application.properties或application.yml是主配置文件。5.1 基础配置示例# 应用服务端口 server.port8081 # 应用上下文路径访问地址变为 http://localhost:8081/myapp/hello server.servlet.context-path/myapp # 数据库连接配置 (以MySQL为例) spring.datasource.urljdbc:mysql://localhost:3306/testdb?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai spring.datasource.usernameroot spring.datasource.passwordyourpassword spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver # JPA/Hibernate配置 spring.jpa.hibernate.ddl-autoupdate # 开发环境常用根据实体更新表结构 spring.jpa.show-sqltrue # 控制台显示SQL语句 spring.jpa.properties.hibernate.dialectorg.hibernate.dialect.MySQL8Dialect # 日志级别配置可以精确到包 logging.level.rootINFO logging.level.com.example.demoDEBUG logging.level.org.springframework.webDEBUGYAML格式的等价配置看起来更清晰server: port: 8081 servlet: context-path: /myapp spring: datasource: url: jdbc:mysql://localhost:3306/testdb?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver jpa: hibernate: ddl-auto: update show-sql: true properties: hibernate: dialect: org.hibernate.dialect.MySQL8Dialect logging: level: root: INFO com.example.demo: DEBUG org.springframework.web: DEBUG5.2 多环境配置与Profile在实际开发中我们会有开发dev、测试test、生产prod等不同环境。Spring Boot通过application-{profile}.properties/yml来支持。application-dev.properties开发环境配置。application-prod.properties生产环境配置。在主配置文件application.properties中可以通过spring.profiles.active来激活特定的环境配置。spring.profiles.activedev在运行时也可以通过JVM参数或环境变量来指定-Dspring.profiles.activeprod或export SPRING_PROFILES_ACTIVEprod。5.3 配置的优先级与外部化Spring Boot的配置有一个严格的优先级顺序高优先级的配置会覆盖低优先级的。从高到低大致如下命令行参数--server.port9000。Java系统属性-Dserver.port9000。操作系统环境变量SERVER_PORT9000注意命名规则转换点.换成下划线_大写。当前目录下的/config子目录中的配置文件。当前目录下的配置文件。classpath下的/config包中的配置文件。classpath根目录下的配置文件即我们常用的application.properties。这个特性使得配置可以非常灵活地从外部注入特别是在容器化Docker部署时通过环境变量来管理敏感配置如数据库密码是最佳实践。6. 依赖管理、Starter与自动配置揭秘这是Spring Boot魔法发生的核心区域。6.1 Starter依赖一站式功能包Starter是一组预定义的依赖描述符。例如当你添加spring-boot-starter-web时你实际上引入了Spring MVC框架内嵌的Tomcat服务器JacksonJSON处理库验证APIHibernate Validator等等你不需要手动去查找和协调这些库的版本Starter已经帮你管理好了并且保证了它们之间的兼容性。这就是“约定大于配置”的体现——你声明你需要“Web”功能Spring Boot就给你一套经过验证的最佳组合。6.2 自动配置条件化装配BeanSpring Boot的自动配置基于Conditional注解及其变体。启动时Spring Boot会扫描classpath下的依赖根据条件决定是否创建某些Bean。例如当classpath下存在HikariCP这个数据库连接池类时DataSourceAutoConfiguration就会自动为你配置一个DataSourceBean。当你自己在配置类中显式定义了一个DataSourceBean时自动配置的Bean就不会被创建因为ConditionalOnMissingBean条件不满足了。你可以通过查看spring-boot-autoconfigure包的META-INF/spring.factories文件或Spring Boot 2.7后的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件来了解所有自动配置类。在应用启动时将日志级别设置为DEBUG也能在控制台看到一份“Positive matches”匹配成功和“Negative matches”匹配失败的自动配置报告这对于调试为什么某个功能没有自动生效非常有帮助。6.3 处理依赖冲突随着项目引入的依赖越来越多难免会出现传递依赖冲突即同一个类库的不同版本被引入。这可能导致NoSuchMethodError或ClassNotFoundException等运行时错误。排查工具Maven依赖树在项目根目录执行mvn dependency:tree。这个命令会以树形结构展示所有依赖及其传递关系。仔细查看输出找到冲突的库看是哪个路径引入了非预期的版本。IDE可视化工具IntelliJ IDEA和Eclipse都有优秀的依赖分析工具可以图形化地显示依赖关系并高亮冲突。解决方案排除传递依赖在pom.xml中在引入依赖的dependency标签内使用exclusions。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId !-- 排除内嵌Tomcat -- /exclusion /exclusions /dependency统一版本管理在properties标签中定义版本号然后在依赖中引用。Spring Boot的父POM已经为大量常用库做了这件事。对于非Spring Boot管理的库你也可以在dependencyManagement中统一声明版本。7. 开发中的实用技巧与避坑指南结合网络热词中提到的“knife4j文档请求异常”、“mybatis步骤”、“nacos配置”等这里分享一些实战中的经验。7.1 集成API文档工具以SpringDoc OpenAPI为例“knife4j文档请求异常”常出现在Spring Boot 3中因为Spring Boot 3移除了对旧版SpringMVC 5.x的兼容而老版本的springfoxSwagger 2与之不兼容。解决方案是使用SpringDoc OpenAPI它是OpenAPI 3规范的原生实现。集成步骤添加依赖在start.spring.io上可以直接选择SpringDoc OpenAPI依赖dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.5.0/version !-- 使用最新版本 -- /dependency启动应用访问http://localhost:8080/swagger-ui.html默认路径可通过springdoc.swagger-ui.path配置修改。你会发现一个功能完善的Swagger UI界面所有标有RestController的接口都会自动被扫描和展示。使用Operation,Parameter,ApiResponse等注解来增强接口描述。注意如果遇到文档请求异常检查是否引入了错误的依赖版本或者是否有自定义的拦截器/过滤器影响了/v3/api-docs或/swagger-ui/**路径的访问。7.2 集成MyBatis或MyBatis-Plus“eclipse在spring boot中搭配mybatis步骤”是一个经典需求。MyBatis是一个优秀的持久层框架。核心步骤添加依赖除了数据库驱动还需要mybatis-spring-boot-starter。dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency配置数据源如前文所示在application.properties中配置spring.datasource。配置MyBatis指定Mapper接口所在的包、XML映射文件的位置等。# 指定MyBatis mapper接口的扫描包 mybatis.mapper-locationsclasspath:mapper/*.xml # 指定实体类的包用于别名简化 mybatis.type-aliases-packagecom.example.demo.entity # 开启驼峰命名自动映射数据库user_name - 实体类userName mybatis.configuration.map-underscore-to-camel-casetrue创建实体类Entity、Mapper接口使用Mapper注解或通过MapperScan在启动类上扫描以及对应的XML映射文件如果使用XML方式。在Service中注入Mapper接口即可使用。避坑点XML文件位置确保mapper-locations配置的路径正确且XML文件在编译后确实存在于classpath的对应位置。IDEA中XML文件不编译如果XML文件放在src/main/java目录下默认Maven不会将其复制到target/classes。通常建议将XML文件放在src/main/resources的对应目录下如resources/mapper/。属性名映射务必确认map-underscore-to-camel-case配置是否符合你的数据库和实体类命名习惯。7.3 集成配置中心以Nacos为例“spring boot 2.4 nacos 配置”指向了微服务架构下的配置管理。Nacos既可以作为服务注册中心也可以作为配置中心。Spring Boot 2.4 集成Nacos Config Spring Boot 2.4对配置加载机制进行了重大改动引入了新的spring.config.import方式这影响了Nacos等配置中心的集成方式。添加依赖dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId version2022.0.0.0/version !-- 版本需与Spring Boot和Spring Cloud对应 -- /dependency在bootstrap.properties或bootstrap.yml中配置Nacos服务器地址和数据ID。注意Spring Cloud 2020.0.0 (Ilford) 之后默认不再自动启用bootstrap上下文需要额外引入spring-cloud-starter-bootstrap依赖或者使用application.properties配合spring.config.import。方式一使用bootstrap传统: 添加spring-cloud-starter-bootstrap依赖然后创建bootstrap.propertiesspring.application.nameyour-service-name spring.cloud.nacos.config.server-addr127.0.0.1:8848 spring.cloud.nacos.config.file-extensionyaml # 配置内容格式默认为properties方式二使用spring.config.import推荐: 在application.properties中配置spring.application.nameyour-service-name spring.config.importoptional:nacos:${spring.application.name}.yaml spring.cloud.nacos.config.server-addr127.0.0.1:8848在Nacos控制台上创建对应的配置Data ID为${spring.application.name}.${file-extension}如your-service-name.yaml。在应用中使用Value或ConfigurationProperties来注入配置就像使用本地配置一样。配置变更时应用会自动刷新需配合RefreshScope注解。关键点务必注意Spring Boot、Spring Cloud Alibaba、Nacos Client三者版本的兼容性版本不匹配是大部分集成失败的原因。官方GitHub的Wiki或Release Notes中有详细的版本对应关系表。7.4 关于安全漏洞CVE的应对像“cve-2025-22235”这样的安全漏洞提醒我们需要关注依赖的安全性。Spring Boot本身及其依赖的库可能暴露出安全漏洞。应对策略保持版本更新定期升级Spring Boot到最新的稳定版本。Spring Boot团队会及时为受支持的版本分支提供安全补丁。使用依赖检查工具集成像OWASP Dependency-Check这样的工具到你的构建流程中。Maven插件可以在编译时检查项目依赖是否存在已知的公共漏洞。关注官方公告订阅Spring官方博客或安全邮件列表及时获取安全通告。理解漏洞影响不是所有CVE都对你的应用构成实际威胁。需要阅读漏洞描述判断其影响范围是否需要特定配置、是否被默认启用等。例如某个漏洞可能只影响Actuator端点而你的生产环境可能根本没有暴露Actuator。8. 打包、部署与生产就绪开发完成后我们需要将应用部署到生产环境。8.1 打包为可执行Jar使用Maven命令mvn clean package。打包后在target目录下会生成两个jar文件假设打包方式为jardemo-0.0.1-SNAPSHOT.jar这是可执行的“fat jar”它包含了所有编译后的类、资源文件以及内嵌的依赖库。你可以直接用java -jar demo-0.0.1-SNAPSHOT.jar运行。demo-0.0.1-SNAPSHOT.jar.original这是普通的jar只包含你项目的代码不包含依赖。Spring Boot的Maven插件spring-boot-maven-plugin负责了这个打包魔法。它使用一个特殊的类加载器架构org.springframework.boot.loader.Launcher来启动内嵌在Jar包中的依赖。8.2 生产环境配置关闭开发特性确保生产配置中关闭了spring.jpa.hibernate.ddl-autoupdate建议使用validate或none并通过Flyway/Liquibase管理数据库变更关闭spring.jpa.show-sql并将日志级别调整为WARN或ERROR。管理敏感信息绝对不要将数据库密码、API密钥等硬编码在配置文件中或提交到代码仓库。使用环境变量、配置中心如Nacos或云服务商提供的密钥管理服务。健康检查与监控Spring Boot Actuator提供了丰富的生产就绪特性如健康检查、指标收集、环境信息等。通过添加spring-boot-starter-actuator依赖并适当配置暴露的端点注意生产环境要保护敏感端点可以方便地与监控系统如Prometheus集成。management.endpoints.web.exposure.includehealth,info,metrics,prometheus management.endpoint.health.show-detailswhen_authorized8.3 替换内嵌Web服务器“spring boot 中tomcat替换成国产中间件宝蓝德”这个热词提到了替换内嵌服务器。Spring Boot默认使用Tomcat但可以轻松替换为Jetty或Undertow甚至是其他兼容Servlet规范的服务器。以替换为Undertow为例在pom.xml中排除默认的Tomcat starter并引入Undertow starter。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId /exclusion /exclusions /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-undertow/artifactId /dependency重新启动应用你会发现控制台日志中服务器变成了Undertow。Undertow在高并发场景下可能具有更好的性能和内存占用表现。至于替换为“宝蓝德”或其他国产中间件原理是类似的需要该中间件提供符合Servlet规范的实现并封装成Spring Boot Starter。你需要找到对应的starter依赖并按照其文档进行排除和引入操作。这通常需要该中间件厂商提供官方的Spring Boot集成支持。