行全流程解析：從環(huán)境準(zhǔn)備到啟動(dòng)調(diào)試避坑指南)
先聊點(diǎn)實(shí)在的。SpringBoot項(xiàng)目本地跑不起來十有八九不是代碼的問題而是環(huán)境、依賴和配置這三座大山?jīng)]挪開。很多新手甚至干了三五年的老手換臺(tái)電腦、換個(gè)項(xiàng)目就抓瞎本質(zhì)上是對(duì)SpringBoot本地運(yùn)行的完整鏈路沒有一個(gè)清晰的認(rèn)識(shí)。這篇文章我就把從零到一啟動(dòng)一個(gè)SpringBoot項(xiàng)目的完整流程拆開揉碎講清楚包括環(huán)境準(zhǔn)備、項(xiàng)目構(gòu)建、配置調(diào)優(yōu)、啟動(dòng)調(diào)試還有一籮筐只有實(shí)操才能踩到的坑。無論你是剛?cè)腴T想跑通第一個(gè)Demo還是工作中需要頻繁切換項(xiàng)目的老手這篇文章都能讓你少走彎路。1. 整體思路本地運(yùn)行SpringBoot到底在跑什么很多教程上來就讓你敲mvn spring-boot:run跑通了就算完事。但你要是沒想明白背后發(fā)生了什么出了問題照樣抓瞎。本地運(yùn)行一個(gè)SpringBoot項(xiàng)目本質(zhì)上是在你的機(jī)器上完成三件事準(zhǔn)備運(yùn)行時(shí)環(huán)境、構(gòu)建項(xiàng)目產(chǎn)物、啟動(dòng)內(nèi)嵌容器。1.1 核心鏈路拆解SpringBoot之所以能“一鍵啟動(dòng)”核心在于它內(nèi)嵌了Servlet容器默認(rèn)Tomcat。傳統(tǒng)的Web項(xiàng)目需要你把War包丟到外部Tomcat的webapps目錄里再啟動(dòng)Tomcat才能訪問。SpringBoot直接通過main方法啟動(dòng)一個(gè)應(yīng)用上下文同時(shí)把Tomcat作為內(nèi)嵌依賴?yán)饋肀O(jiān)聽端口。這意味著你只需要一個(gè)Java運(yùn)行環(huán)境不需要額外安裝任何Web服務(wù)器。整個(gè)啟動(dòng)鏈路大致如下構(gòu)建工具M(jìn)aven或Gradle讀取配置文件下載依賴。編譯源碼和資源文件生成Class文件。spring-boot-maven-plugin或Gradle插件打包/直接運(yùn)行。SpringApplication.run()啟動(dòng)應(yīng)用上下文自動(dòng)裝配生效。內(nèi)嵌Tomcat啟動(dòng)監(jiān)聽配置的端口完成服務(wù)注冊(cè)。1.2 方案選型的考量點(diǎn)構(gòu)建工具的選擇上Maven依然是絕對(duì)的主流Gradle雖然有更快的增量構(gòu)建和更靈活的腳本但中小型團(tuán)隊(duì)和大多數(shù)開源項(xiàng)目還是以Maven為主。如果你的項(xiàng)目已經(jīng)存在跟著項(xiàng)目的pom.xml走就行別輕易換構(gòu)建工具——Gradle和Maven的依賴管理邏輯雖然兼容但切換成本絕對(duì)超出你的預(yù)期。JDK版本的選擇更是個(gè)敏感話題。現(xiàn)在Spring Boot 2.x要求JDK 8起步Spring Boot 3.x直接要求JDK 17。我發(fā)現(xiàn)不少朋友在這上面翻車本地裝了好幾個(gè)JDK版本環(huán)境變量配的是8結(jié)果拉了個(gè)Spring Boot 3.x的項(xiàng)目編譯直接報(bào)錯(cuò)。后面我會(huì)專門講怎么科學(xué)地管理多版本JDK。2. 環(huán)境準(zhǔn)備本地運(yùn)行的基石這一部分說的都是干貨建議你按順序檢查一遍自己的環(huán)境。很多“莫名其妙”的報(bào)錯(cuò)根源都出在環(huán)境不對(duì)齊。2.1 JDK與Maven的版本匹配先說JDK。如果你同時(shí)處理多個(gè)項(xiàng)目我非常建議你使用版本管理工具而不是手動(dòng)改環(huán)境變量。Windows上我推薦用Scoop或choco安裝多版本JDKmacOS或Linux用戶直接用sdkman一條命令切換版本省心太多。Maven版本和JDK的匹配關(guān)系很多人不重視。Maven 3.6.3以下版本對(duì)JDK 17支持不友好構(gòu)建時(shí)會(huì)報(bào)Unsupported class file major version這類的錯(cuò)。我個(gè)人的習(xí)慣是JDK 8項(xiàng)目Maven 3.6.3或3.8.xJDK 11項(xiàng)目Maven 3.8.xJDK 17項(xiàng)目Maven 3.9.xJAVA_HOME的配置必須和你在命令行里敲java -version看到的一致。我曾經(jīng)排查過一起詭異問題IDEA里終端跑Maven正常系統(tǒng)命令行跑就報(bào)錯(cuò)最后發(fā)現(xiàn)是IDEA內(nèi)置終端加載了不同的環(huán)境變量。2.2 依賴鏡像源配置國內(nèi)網(wǎng)絡(luò)環(huán)境拉Maven依賴不配鏡像源幾乎是等死的節(jié)奏。默認(rèn)中央倉庫的速度因網(wǎng)絡(luò)環(huán)境而異最好直接在settings.xml里配置阿里云鏡像或騰訊云鏡像速度穩(wěn)定得多。順帶說一句settings.xml的位置很關(guān)鍵全局配置$MAVEN_HOME/conf/settings.xml用戶配置~/.m2/settings.xml用戶配置優(yōu)先級(jí)高于全局配置。我見過有人改了全局配置沒生效就是因?yàn)橛脩裟夸浵麓嬖谝环輘ettings.xml覆蓋了它。配置完鏡像源如果依賴下載還是一堆Could not resolve錯(cuò)誤優(yōu)先檢查pom.xml里有沒有引用私有倉庫以及本機(jī)能否訪問該倉庫地址。很多公司內(nèi)部私服只允許內(nèi)網(wǎng)訪問在家加班調(diào)試時(shí)就會(huì)拉取失敗。2.3 IDE的選型與核心配置IDE方面IDEA是SpringBoot開發(fā)的絕對(duì)主力社區(qū)版其實(shí)也能跑但如果你想用Spring Initializr快速創(chuàng)建項(xiàng)目、或者使用Spring Boot的圖形化運(yùn)行配置直接上Ultimate版。Eclipse和VS Code雖然也能開發(fā)但體驗(yàn)和生態(tài)差距明顯我不會(huì)推薦新手在工具上省事。IDEA里建議手動(dòng)配置而不是直接依賴自動(dòng)導(dǎo)入Settings - Build, Execution, Deployment - Build Tools - Maven指定Maven home directory為本地安裝路徑。User settings file和Local repository設(shè)為實(shí)際使用的路徑。開啟Always update snapshots——這一點(diǎn)見仁見智如果你的項(xiàng)目頻繁迭代SNAPSHOT依賴建議勾上但代價(jià)是每次構(gòu)建都會(huì)檢查遠(yuǎn)程快照更新速度會(huì)慢一些。3. 項(xiàng)目創(chuàng)建與結(jié)構(gòu)解析有了環(huán)境接下來就是項(xiàng)目本身。這里分兩種情況一是你自己新建項(xiàng)目二是接手別人的項(xiàng)目。3.1 快速創(chuàng)建SpringBoot項(xiàng)目最標(biāo)準(zhǔn)的姿勢(shì)是通過 Spring Initializr 生成。你可以直接用瀏覽器訪問這個(gè)網(wǎng)站選擇構(gòu)建工具、語言、Spring Boot版本和依賴然后點(diǎn)擊生成并下載壓縮包。IDEA用戶更簡單新建Project選擇Spring Initializr填好Group和Artifact勾選需要的依賴IDEA會(huì)直接幫你生成一個(gè)可運(yùn)行的空項(xiàng)目。需要注意的一點(diǎn)是Spring Initializr上的版本通常是最新穩(wěn)定版但如果你要對(duì)接的公司內(nèi)部中間件版本較老最好在生成后手動(dòng)調(diào)整pom.xml里的版本號(hào)?；A(chǔ)依賴的選擇有個(gè)經(jīng)驗(yàn)法則剛開始跑項(xiàng)目只加最少必要的依賴。比如一個(gè)Web接口服務(wù)只需要Spring Web就夠了。數(shù)據(jù)訪問相關(guān)的MyBatis、JPA等等寫到了再加不要一次性全勾上——依賴多了啟動(dòng)時(shí)自動(dòng)裝配的復(fù)雜度會(huì)直線上升排查問題的難度也隨之變大。3.2 pom.xml解析這些標(biāo)簽?zāi)惚仨毝粋€(gè)典型的pom.xml核心結(jié)構(gòu)如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependenciesspring-boot-starter-parent承擔(dān)了依賴版本管理dependency management的核心任務(wù)。它內(nèi)部定義了一大堆常用依賴的版本號(hào)你引入spring-boot-starter-web時(shí)不用寫version就是因?yàn)樗呀?jīng)幫你鎖定了版本。這是SpringBoot最聰明的設(shè)計(jì)之一但也是問題高發(fā)區(qū)——如果你在dependencies中手動(dòng)指定了一個(gè)高版本依賴而該依賴和SpringBoot默認(rèn)版本不兼容啟動(dòng)階段就會(huì)出現(xiàn)各種NoSuchMethodError或ClassNotFoundException。還有一個(gè)關(guān)鍵的插件配置build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build這個(gè)插件有兩個(gè)核心功能打包可執(zhí)行的Jar包以及支持mvn spring-boot:run直接運(yùn)行項(xiàng)目。沒有這個(gè)插件你在本地可能仍然能通過java -cp手動(dòng)指定Classpath運(yùn)行但會(huì)痛苦得多。它還會(huì)在打包時(shí)把依賴和啟動(dòng)腳本一起處理生成一個(gè)Fat Jar。3.3 目錄結(jié)構(gòu)約定優(yōu)于配置SpringBoot項(xiàng)目的標(biāo)準(zhǔn)目錄結(jié)構(gòu)長這樣src ├── main │ ├── java │ │ └── com/example/demo │ │ ├── DemoApplication.java │ │ ├── controller │ │ ├── service │ │ ├── mapper │ │ └── config │ └── resources │ ├── application.yml │ ├── static │ └── templates └── test └── javaDemoApplication.java就是啟動(dòng)類它上面標(biāo)注了SpringBootApplication。這個(gè)注解是個(gè)組合注解包含了SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。這里有個(gè)大坑啟動(dòng)類必須放在最外層包也就是com.example.demo這個(gè)層級(jí)。因?yàn)镃omponentScan默認(rèn)掃描啟動(dòng)類所在包及其子包如果你把啟動(dòng)類放到controller的上一層之外Spring就掃描不到你的Controller和Service接口全404。3.4 配置文件的核心知識(shí)本地運(yùn)行最重要的配置文件是src/main/resources/application.yml或application.properties。我用YAML格式比較多它層次清晰適合配置較多的場景?；A(chǔ)配置示例server: port: 8080 servlet: context-path: /demo spring: application: name: demo-service datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver這里補(bǔ)充一個(gè)關(guān)鍵原則本地配置永遠(yuǎn)不要和線上配置混在一起。哪怕你圖省事也至少通過Spring Profiles區(qū)分開。方法很簡單application.yml公共配置。application-dev.yml本地開發(fā)環(huán)境配置。application-prod.yml生產(chǎn)環(huán)境配置。啟動(dòng)時(shí)通過spring.profiles.activedev指定激活哪個(gè)環(huán)境。這樣你的本地?cái)?shù)據(jù)庫連接、日志級(jí)別、端口號(hào)都可以和線上保持隔離。我之前接手過一個(gè)項(xiàng)目開發(fā)環(huán)境的數(shù)據(jù)庫密碼直接寫在application.yml里結(jié)果代碼上傳到Git倉庫后密碼泄露——這種教訓(xùn)太普遍了。正確的做法是把敏感配置放到環(huán)境變量或配置中心本地運(yùn)行時(shí)通過SPRING_DATASOURCE_PASSWORD這個(gè)環(huán)境變量注入。4. 本地運(yùn)行與調(diào)試全流程環(huán)境配好了代碼也有了現(xiàn)在來到最關(guān)鍵的一環(huán)把項(xiàng)目跑起來。這里我講兩種方式以及各自適合的場景。4.1 方式一IDEA圖形化運(yùn)行這是最順手的方式也是大多數(shù)開發(fā)者的日常操作。在IDEA中找到主啟動(dòng)類DemoApplication。右鍵點(diǎn)擊選擇Run DemoApplication。觀察底部控制臺(tái)輸出。正常情況下你會(huì)看到Spring的Banner、一堆自動(dòng)裝配的日志最后是Tomcat started on port(s): 8080 (http) with context path Started DemoApplication in 3.2 seconds看到Started關(guān)鍵字說明你的項(xiàng)目已經(jīng)成功啟動(dòng)。但這里有一個(gè)頻率極高的坑第一次啟動(dòng)很可能失敗。最常見的報(bào)錯(cuò)是Port 8080 was already in use。原因很簡單8080端口被其他進(jìn)程占用了。排查方式Windowsnetstat -ano | findstr 8080macOS/Linuxlsof -i:8080找到占用進(jìn)程的PID后殺掉它或者更優(yōu)雅的做法——在application.yml里換一個(gè)端口server: port: 80814.2 方式二Maven命令行運(yùn)行有些人習(xí)慣不用IDE或者在遠(yuǎn)程服務(wù)器上調(diào)試命令行方式就離不開。在項(xiàng)目根目錄執(zhí)行mvn spring-boot:run這個(gè)命令會(huì)先做編譯再啟動(dòng)應(yīng)用。它的好處是和你后續(xù)在CI/CD中用到的命令一致排除了IDE帶來的隱藏差異。比如IDEA有時(shí)會(huì)用自己緩存的舊Class文件導(dǎo)致行為和命令行不一致而命令行永遠(yuǎn)是干凈的。如果你想先跳過測試編譯來加速啟動(dòng)本地調(diào)試時(shí)不建議跑測試太耗時(shí)mvn spring-boot:run -DskipTests如果項(xiàng)目模塊多只想運(yùn)行指定模塊mvn spring-boot:run -pl your-module-name-pl指定模塊路徑后續(xù)還可以加-am讓Maven同時(shí)構(gòu)建其依賴模塊。4.3 打Jar包運(yùn)行偶爾會(huì)遇到需要在本地模擬生產(chǎn)環(huán)境跑的情況這時(shí)就用打包方式mvn clean package -DskipTests指定輸出目錄、跳過測試java -jar target/demo-0.0.1-SNAPSHOT.jar用Jar包方式啟動(dòng)時(shí)如果你在pom.xml中配置了多個(gè)Profile可以用啟動(dòng)參數(shù)指定Profilejava -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.activedev也可以臨時(shí)覆蓋端口java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port8082這一點(diǎn)非常實(shí)用--后面的參數(shù)優(yōu)先級(jí)高于配置文件是Spring Boot配置體系里“命令行參數(shù) Java系統(tǒng)屬性 環(huán)境變量 application.yml”的體現(xiàn)。4.4 熱部署配置本地開發(fā)最讓人煩躁的事情之一就是改一行代碼需要重啟整個(gè)應(yīng)用。Spring Boot官方提供了spring-boot-devtools來解決這個(gè)問題。在pom.xml中添加dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency然后在application.yml里配置spring: devtools: restart: enabled: true原理是devtools監(jiān)控Classpath下的文件變化一旦檢測到變化自動(dòng)重啟應(yīng)用。但要注意重啟不等于熱部署它實(shí)際上是快速重啟不是像JRebel那樣做到方法級(jí)別的熱替換。對(duì)于日常開發(fā)來說快速重啟已經(jīng)能省下大量時(shí)間。我自己習(xí)慣配合IDEA的Build project automatically選項(xiàng)改完代碼按一下CtrlF10或直接切出IDE窗口讓它自動(dòng)構(gòu)建并觸發(fā)重啟。再多配置一步Settings - Advanced Settings - Allow auto-make to start even if developed application is currently running勾上之后體驗(yàn)更好。4.5 遠(yuǎn)程調(diào)試本地運(yùn)行還有一個(gè)容易被忽略但非常實(shí)用的功能遠(yuǎn)程調(diào)試。當(dāng)你在本地啟動(dòng)的應(yīng)用需要和另一個(gè)進(jìn)程比如本地的網(wǎng)關(guān)、另一個(gè)微服務(wù)進(jìn)行聯(lián)調(diào)時(shí)端口級(jí)別的遠(yuǎn)程調(diào)試能幫大忙。在啟動(dòng)命令或IDE的VM options中添加-agentlib:jdwptransportdt_socket,servery,suspendn,address5005然后本地的另一個(gè)IDEA實(shí)例通過Run - Attach to Process連接5005端口就能打斷點(diǎn)調(diào)試了。這個(gè)技能在調(diào)試多模塊項(xiàng)目時(shí)意義很大。5. 常見啟動(dòng)問題與排查實(shí)錄這一節(jié)是全文最有價(jià)值的部分。下面這些坑我全都親手踩過每一個(gè)都花了不少時(shí)間才排查清楚。5.1 依賴沖突先看一個(gè)典型的報(bào)錯(cuò)*************************** APPLICATION FAILED TO START *************************** Description: An attempt was made to call a method that does not exist. The attempt was made from the following location: ...這種問題八成的可能是依賴版本沖突。SpringBoot的自動(dòng)版本管理幫你省了很多事但一旦有某個(gè)依賴你手動(dòng)指定了版本或者某個(gè)傳遞依賴和SpringBoot內(nèi)置版本不一致就會(huì)出現(xiàn)這種情況。排查步驟執(zhí)行mvn dependency:tree看依賴樹。搜索沖突的GAVGroupId、ArtifactId、Version。用mvn dependency:analyze檢查無用依賴和缺失依賴。比如常見的spring-boot-starter-data-redis底層引入了lettuce-core如果你想用Jedis就必須排除lettuce添加jedis依賴。不排除就會(huì)導(dǎo)致兩個(gè)Redis客戶端共存行為怪異的很。5.2 自動(dòng)配置類報(bào)錯(cuò)Description: Failed to configure a DataSource: url attribute is not specified and no embedded datasource could be configured. Reason: Failed to determine a suitable driver class如果你只是引入spring-boot-starter-data-jpa或mybatis-spring-boot-starter但沒有配置數(shù)據(jù)庫連接信息啟動(dòng)時(shí)就會(huì)報(bào)這個(gè)錯(cuò)。原因在于SpringBoot自動(dòng)裝配嘗試創(chuàng)建DataSource實(shí)例但沒有拿到連接信息。解決方案也簡單如果暫時(shí)不需要數(shù)據(jù)庫操作把對(duì)應(yīng)依賴從pom.xml中移除?；蛘呓oSpringBootApplication加一個(gè)排除屬性SpringBootApplication(exclude {DataSourceAutoConfiguration.class})這個(gè)排除操作僅建議在臨時(shí)調(diào)試時(shí)使用真正開發(fā)時(shí)還是老老實(shí)實(shí)配上數(shù)據(jù)源。5.3 include相關(guān)漏配導(dǎo)致的404項(xiàng)目能啟動(dòng)但訪問接口是404。這種情況很迷惑人因?yàn)轫?xiàng)目看起來一切正常。排查思路按照從外到內(nèi)確認(rèn)訪問路徑是否正確context-path有沒有配RequestMapping的路徑對(duì)不對(duì)確認(rèn)Controller是否被掃描到檢查啟動(dòng)類是否在包的頂層。確認(rèn)RestController還是Controller如果是Controller接口方法返回字符串時(shí)可能會(huì)被Spring MVC當(dāng)作視圖名處理而不是直接返回內(nèi)容導(dǎo)致響應(yīng)內(nèi)容和預(yù)期不符。5.4 編碼問題導(dǎo)致的亂碼中文亂碼在本地運(yùn)行中很常見分兩種控制臺(tái)亂碼和響應(yīng)亂碼?？刂婆_(tái)亂碼多半是IDEA控制臺(tái)編碼和項(xiàng)目編碼不一致。設(shè)置里把File Encodings全部調(diào)整為UTF-8同時(shí)修改IDEA安裝目錄bin下的idea64.exe.vmoptions文件加上-Dfile.encodingUTF-8響應(yīng)亂碼則可能是你返回的字符串在HTTP傳輸時(shí)編碼問題。SpringBoot默認(rèn)已經(jīng)設(shè)置為UTF-8但如果你在代碼中手動(dòng)處理了字節(jié)流或者用了舊的HttpMessageConverter就可能踩坑。最簡單的排查方式是在application.yml中顯式聲明server: servlet: encoding: charset: UTF-8 enabled: true force: true5.5 內(nèi)存溢出本地跑大型項(xiàng)目時(shí)JVM默認(rèn)堆內(nèi)存太小容易崩潰。IDEA默認(rèn)的堆內(nèi)存設(shè)置往往不夠用如果你看到j(luò)ava.lang.OutOfMemoryError: Java heap space或干脆應(yīng)用進(jìn)程被殺。處理方式是在運(yùn)行配置中調(diào)整VM options-Xms512m -Xmx2048m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m如果你的項(xiàng)目編譯很重、依賴特別多Metaspace可以適當(dāng)調(diào)大一些。順手建議把-XX:HeapDumpOnOutOfMemoryError加上JVM可以在崩潰時(shí)導(dǎo)出堆轉(zhuǎn)儲(chǔ)文件方便排查內(nèi)存泄漏。5.6 配置文件未生效你改了application.yml里的端口重啟后還是8080。這種問題很詭異最常見的原因是配置文件根本沒被加載。檢查文件是否在src/main/resources目錄下。文件名是否是application.yml或application-{profile}.yml。是否同時(shí)在application.properties和application.yml中配置了同一屬性——如果兩個(gè)文件都存在application.properties優(yōu)先級(jí)高于application.yml你改YAML文件當(dāng)然不生效。命令行是否有--server.port參數(shù)覆蓋了配置文件。5.7 端口被占用速查表用一張表做個(gè)總結(jié)以后遇到端口問題直接對(duì)照排查報(bào)錯(cuò)信息原因解決方案Port 8080 was already in use端口被其他進(jìn)程占用殺進(jìn)程或換端口Address already in use網(wǎng)絡(luò)地址被占用可能是Socket未釋放lsof -i:端口找PID殺掉Error creating bean with name tomcatServletWebServerFactory端口綁定失敗檢查是否有特權(quán)端口小于1024Web server failed to start. Port X was already in use同上在配置文件中更換端口5.8 Lombok依賴問題Lombok是SpringBoot項(xiàng)目里很常見的依賴但它有個(gè)特點(diǎn)必須在編譯期通過注解處理器生成代碼。如果你啟動(dòng)時(shí)報(bào)各種getter/setter找不到或者java: package lombok does not exist大概率是Lombok版本和JDK版本不兼容。JDK 8 Lombok 1.18.20及以下正常。JDK 11需要Lombok 1.18.20以上。JDK 17需要Lombok 1.18.24以上。JDK 21需要Lombok 1.18.30以上。同時(shí)IDEA的Settings - Build - Compiler - Annotation Processors勾選Enable annotation processing。這步漏了IDEA里會(huì)瘋狂報(bào)找不到符號(hào)。5.9 多模塊項(xiàng)目的本地運(yùn)行微服務(wù)項(xiàng)目在本地運(yùn)行時(shí)經(jīng)常會(huì)出現(xiàn)跨模塊聯(lián)調(diào)問題。典型場景A服務(wù)調(diào)用B服務(wù)B沒啟動(dòng)A服務(wù)報(bào)連接拒絕。排查思路確認(rèn)B服務(wù)的地址和端口是否配置正確。確認(rèn)A服務(wù)的注冊(cè)中心如Nacos、Eureka是否可達(dá)。如果走的是Feign/OpenFeign檢查超時(shí)時(shí)間和熔斷配置。這里有個(gè)小技巧本地調(diào)試時(shí)可以把注冊(cè)中心的配置指向本地啟動(dòng)的Nacos只啟動(dòng)需要的兩個(gè)服務(wù)其他的服務(wù)都關(guān)掉效率高很多。6. 進(jìn)階技巧與最佳實(shí)踐6.1 啟動(dòng)參數(shù)里的SpringApplication.run有人會(huì)有疑問cmd上能不能省掉--前綴實(shí)際上SpringBoot命令行參數(shù)有兩種寫法java -jar app.jar --server.port8081 java -jar app.jar -Dserver.port8081第一種寫法是SpringBoot命名的參數(shù)--第二種是JVM系統(tǒng)屬性-D。兩者都能生效但優(yōu)先級(jí)不同--參數(shù)優(yōu)先級(jí)更高。如果你發(fā)現(xiàn)配置文件改了不生效先看看啟動(dòng)命令里是不是有這兩種參數(shù)在“強(qiáng)覆蓋”。6.2 啟動(dòng)時(shí)的Banner優(yōu)化SpringBoot默認(rèn)啟動(dòng)時(shí)會(huì)在控制臺(tái)打印一個(gè)大大的“Spring”字符畫。如果你覺得太占地方或者想在日志里標(biāo)記一下版本信息可以在src/main/resources下放一個(gè)banner.txtSpringBoot會(huì)自動(dòng)識(shí)別。網(wǎng)上還有Banner生成器能生成特定字符圖案團(tuán)隊(duì)內(nèi)部用這個(gè)小細(xì)節(jié)來標(biāo)識(shí)環(huán)境dev/test/prod還挺有用。關(guān)閉Banner也很簡單SpringApplication app new SpringApplication(DemoApplication.class); app.setBannerMode(Banner.Mode.OFF); app.run(args);6.3 日志級(jí)別的本地調(diào)整排查問題時(shí)把日志級(jí)別臨時(shí)調(diào)低是最有效的調(diào)試手段之一。logging: level: root: info com.example.demo.mapper: debug這樣配置后MyBatis的SQL日志會(huì)完整打印在控制臺(tái)本地調(diào)試效率提升非常明顯。但記得排查完改回去別把debug級(jí)別的日志帶上生產(chǎn)。6.4 Docker Desktop本地運(yùn)行SpringBoot不少團(tuán)隊(duì)會(huì)用Docker Desktop在本地模擬生產(chǎn)環(huán)境運(yùn)行SpringBoot。這里有個(gè)小坑先構(gòu)建Jar包再寫Dockerfile。如果你依賴遠(yuǎn)程私有倉庫構(gòu)建Docker鏡像時(shí)還需要考慮網(wǎng)絡(luò)問題。最精簡的DockerfileFROM openjdk:8-jdk-alpine COPY target/demo-0.0.1-SNAPSHOT.jar app.jar ENTRYPOINT [java,-jar,/app.jar]如果JDK版本是17基礎(chǔ)鏡像用eclipse-temurin:17-jdk。用Docker啟動(dòng)時(shí)端口映射和文件掛載是高頻出錯(cuò)的點(diǎn)docker run -d -p 8080:8080 -v /path/to/config:/config --env SPRING_PROFILES_ACTIVEdev demo-image6.5 從崩潰到定位的十分鐘排查路徑最后分享一套我自己的本地運(yùn)行故障排查路徑效率極高看啟動(dòng)日志定位第一個(gè)ERROR級(jí)別的堆棧不要從上往下全看而是從下往上找Caused by。確認(rèn)Spring Boot版本和JDK版本是否匹配。執(zhí)行mvn clean清掉舊的編譯產(chǎn)物再重新構(gòu)建。這一步能解決大量“奇怪”問題。檢查配置項(xiàng)是否被Profile覆蓋。如果涉及多個(gè)服務(wù)確認(rèn)依賴服務(wù)的健康狀態(tài)。這套路徑我稱之為“從啟動(dòng)到定位的十分鐘”核心思想是從日志倒推從環(huán)境入手先排除掉最基礎(chǔ)的構(gòu)建問題再去分析業(yè)務(wù)代碼。按這個(gè)順序排查大部分啟動(dòng)故障都能在十分鐘內(nèi)定位到根因。7. 一點(diǎn)個(gè)人的經(jīng)驗(yàn)心得做SpringBoot本地運(yùn)行這件事看起來簡單但真正絲滑地跑起來靠的是對(duì)環(huán)境、構(gòu)建、配置、調(diào)試這四件事的深度理解。我在工作中見過太多人卡在環(huán)境問題上有人JDK版本配錯(cuò)了沒發(fā)現(xiàn)有人Maven鏡像配錯(cuò)了拉不下來依賴有人配置文件里寫錯(cuò)了縮進(jìn)導(dǎo)致屬性沒生效還有人因?yàn)镮DEA緩存問題浪費(fèi)了一下午。我的建議很簡單把環(huán)境當(dāng)代碼一樣管理。用工具鏈固定JDK版本用settings.xml統(tǒng)一Maven配置用Profile隔離每個(gè)環(huán)境的配置把啟動(dòng)和調(diào)試的每一步都做成可重復(fù)的腳本。這樣無論你換多少個(gè)項(xiàng)目、多少臺(tái)電腦都能在十分鐘內(nèi)把項(xiàng)目跑起來。另外遇到問題多看一眼啟動(dòng)日志的Caused by部分那才是真正的病因。 SpringBoot本地運(yùn)行全流程解析：從環(huán)境準(zhǔn)備到啟動(dòng)調(diào)試避坑指南
先聊點(diǎn)實(shí)在的。SpringBoot項(xiàng)目本地跑不起來十有八九不是代碼的問題而是環(huán)境、依賴和配置這三座大山?jīng)]挪開。很多新手甚至干了三五年的老手換臺(tái)電腦、換個(gè)項(xiàng)目就抓瞎本質(zhì)上是對(duì)SpringBoot本地運(yùn)行的完整鏈路沒有一個(gè)清晰的認(rèn)識(shí)。這篇文章我就把從零到一啟動(dòng)一個(gè)SpringBoot項(xiàng)目的完整流程拆開揉碎講清楚包括環(huán)境準(zhǔn)備、項(xiàng)目構(gòu)建、配置調(diào)優(yōu)、啟動(dòng)調(diào)試還有一籮筐只有實(shí)操才能踩到的坑。無論你是剛?cè)腴T想跑通第一個(gè)Demo還是工作中需要頻繁切換項(xiàng)目的老手這篇文章都能讓你少走彎路。1. 整體思路本地運(yùn)行SpringBoot到底在跑什么很多教程上來就讓你敲mvn spring-boot:run跑通了就算完事。但你要是沒想明白背后發(fā)生了什么出了問題照樣抓瞎。本地運(yùn)行一個(gè)SpringBoot項(xiàng)目本質(zhì)上是在你的機(jī)器上完成三件事準(zhǔn)備運(yùn)行時(shí)環(huán)境、構(gòu)建項(xiàng)目產(chǎn)物、啟動(dòng)內(nèi)嵌容器。1.1 核心鏈路拆解SpringBoot之所以能“一鍵啟動(dòng)”核心在于它內(nèi)嵌了Servlet容器默認(rèn)Tomcat。傳統(tǒng)的Web項(xiàng)目需要你把War包丟到外部Tomcat的webapps目錄里再啟動(dòng)Tomcat才能訪問。SpringBoot直接通過main方法啟動(dòng)一個(gè)應(yīng)用上下文同時(shí)把Tomcat作為內(nèi)嵌依賴?yán)饋肀O(jiān)聽端口。這意味著你只需要一個(gè)Java運(yùn)行環(huán)境不需要額外安裝任何Web服務(wù)器。整個(gè)啟動(dòng)鏈路大致如下構(gòu)建工具M(jìn)aven或Gradle讀取配置文件下載依賴。編譯源碼和資源文件生成Class文件。spring-boot-maven-plugin或Gradle插件打包/直接運(yùn)行。SpringApplication.run()啟動(dòng)應(yīng)用上下文自動(dòng)裝配生效。內(nèi)嵌Tomcat啟動(dòng)監(jiān)聽配置的端口完成服務(wù)注冊(cè)。1.2 方案選型的考量點(diǎn)構(gòu)建工具的選擇上Maven依然是絕對(duì)的主流Gradle雖然有更快的增量構(gòu)建和更靈活的腳本但中小型團(tuán)隊(duì)和大多數(shù)開源項(xiàng)目還是以Maven為主。如果你的項(xiàng)目已經(jīng)存在跟著項(xiàng)目的pom.xml走就行別輕易換構(gòu)建工具——Gradle和Maven的依賴管理邏輯雖然兼容但切換成本絕對(duì)超出你的預(yù)期。JDK版本的選擇更是個(gè)敏感話題。現(xiàn)在Spring Boot 2.x要求JDK 8起步Spring Boot 3.x直接要求JDK 17。我發(fā)現(xiàn)不少朋友在這上面翻車本地裝了好幾個(gè)JDK版本環(huán)境變量配的是8結(jié)果拉了個(gè)Spring Boot 3.x的項(xiàng)目編譯直接報(bào)錯(cuò)。后面我會(huì)專門講怎么科學(xué)地管理多版本JDK。2. 環(huán)境準(zhǔn)備本地運(yùn)行的基石這一部分說的都是干貨建議你按順序檢查一遍自己的環(huán)境。很多“莫名其妙”的報(bào)錯(cuò)根源都出在環(huán)境不對(duì)齊。2.1 JDK與Maven的版本匹配先說JDK。如果你同時(shí)處理多個(gè)項(xiàng)目我非常建議你使用版本管理工具而不是手動(dòng)改環(huán)境變量。Windows上我推薦用Scoop或choco安裝多版本JDKmacOS或Linux用戶直接用sdkman一條命令切換版本省心太多。Maven版本和JDK的匹配關(guān)系很多人不重視。Maven 3.6.3以下版本對(duì)JDK 17支持不友好構(gòu)建時(shí)會(huì)報(bào)Unsupported class file major version這類的錯(cuò)。我個(gè)人的習(xí)慣是JDK 8項(xiàng)目Maven 3.6.3或3.8.xJDK 11項(xiàng)目Maven 3.8.xJDK 17項(xiàng)目Maven 3.9.xJAVA_HOME的配置必須和你在命令行里敲java -version看到的一致。我曾經(jīng)排查過一起詭異問題IDEA里終端跑Maven正常系統(tǒng)命令行跑就報(bào)錯(cuò)最后發(fā)現(xiàn)是IDEA內(nèi)置終端加載了不同的環(huán)境變量。2.2 依賴鏡像源配置國內(nèi)網(wǎng)絡(luò)環(huán)境拉Maven依賴不配鏡像源幾乎是等死的節(jié)奏。默認(rèn)中央倉庫的速度因網(wǎng)絡(luò)環(huán)境而異最好直接在settings.xml里配置阿里云鏡像或騰訊云鏡像速度穩(wěn)定得多。順帶說一句settings.xml的位置很關(guān)鍵全局配置$MAVEN_HOME/conf/settings.xml用戶配置~/.m2/settings.xml用戶配置優(yōu)先級(jí)高于全局配置。我見過有人改了全局配置沒生效就是因?yàn)橛脩裟夸浵麓嬖谝环輘ettings.xml覆蓋了它。配置完鏡像源如果依賴下載還是一堆Could not resolve錯(cuò)誤優(yōu)先檢查pom.xml里有沒有引用私有倉庫以及本機(jī)能否訪問該倉庫地址。很多公司內(nèi)部私服只允許內(nèi)網(wǎng)訪問在家加班調(diào)試時(shí)就會(huì)拉取失敗。2.3 IDE的選型與核心配置IDE方面IDEA是SpringBoot開發(fā)的絕對(duì)主力社區(qū)版其實(shí)也能跑但如果你想用Spring Initializr快速創(chuàng)建項(xiàng)目、或者使用Spring Boot的圖形化運(yùn)行配置直接上Ultimate版。Eclipse和VS Code雖然也能開發(fā)但體驗(yàn)和生態(tài)差距明顯我不會(huì)推薦新手在工具上省事。IDEA里建議手動(dòng)配置而不是直接依賴自動(dòng)導(dǎo)入Settings - Build, Execution, Deployment - Build Tools - Maven指定Maven home directory為本地安裝路徑。User settings file和Local repository設(shè)為實(shí)際使用的路徑。開啟Always update snapshots——這一點(diǎn)見仁見智如果你的項(xiàng)目頻繁迭代SNAPSHOT依賴建議勾上但代價(jià)是每次構(gòu)建都會(huì)檢查遠(yuǎn)程快照更新速度會(huì)慢一些。3. 項(xiàng)目創(chuàng)建與結(jié)構(gòu)解析有了環(huán)境接下來就是項(xiàng)目本身。這里分兩種情況一是你自己新建項(xiàng)目二是接手別人的項(xiàng)目。3.1 快速創(chuàng)建SpringBoot項(xiàng)目最標(biāo)準(zhǔn)的姿勢(shì)是通過 Spring Initializr 生成。你可以直接用瀏覽器訪問這個(gè)網(wǎng)站選擇構(gòu)建工具、語言、Spring Boot版本和依賴然后點(diǎn)擊生成并下載壓縮包。IDEA用戶更簡單新建Project選擇Spring Initializr填好Group和Artifact勾選需要的依賴IDEA會(huì)直接幫你生成一個(gè)可運(yùn)行的空項(xiàng)目。需要注意的一點(diǎn)是Spring Initializr上的版本通常是最新穩(wěn)定版但如果你要對(duì)接的公司內(nèi)部中間件版本較老最好在生成后手動(dòng)調(diào)整pom.xml里的版本號(hào)?；A(chǔ)依賴的選擇有個(gè)經(jīng)驗(yàn)法則剛開始跑項(xiàng)目只加最少必要的依賴。比如一個(gè)Web接口服務(wù)只需要Spring Web就夠了。數(shù)據(jù)訪問相關(guān)的MyBatis、JPA等等寫到了再加不要一次性全勾上——依賴多了啟動(dòng)時(shí)自動(dòng)裝配的復(fù)雜度會(huì)直線上升排查問題的難度也隨之變大。3.2 pom.xml解析這些標(biāo)簽?zāi)惚仨毝粋€(gè)典型的pom.xml核心結(jié)構(gòu)如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependenciesspring-boot-starter-parent承擔(dān)了依賴版本管理dependency management的核心任務(wù)。它內(nèi)部定義了一大堆常用依賴的版本號(hào)你引入spring-boot-starter-web時(shí)不用寫version就是因?yàn)樗呀?jīng)幫你鎖定了版本。這是SpringBoot最聰明的設(shè)計(jì)之一但也是問題高發(fā)區(qū)——如果你在dependencies中手動(dòng)指定了一個(gè)高版本依賴而該依賴和SpringBoot默認(rèn)版本不兼容啟動(dòng)階段就會(huì)出現(xiàn)各種NoSuchMethodError或ClassNotFoundException。還有一個(gè)關(guān)鍵的插件配置build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build這個(gè)插件有兩個(gè)核心功能打包可執(zhí)行的Jar包以及支持mvn spring-boot:run直接運(yùn)行項(xiàng)目。沒有這個(gè)插件你在本地可能仍然能通過java -cp手動(dòng)指定Classpath運(yùn)行但會(huì)痛苦得多。它還會(huì)在打包時(shí)把依賴和啟動(dòng)腳本一起處理生成一個(gè)Fat Jar。3.3 目錄結(jié)構(gòu)約定優(yōu)于配置SpringBoot項(xiàng)目的標(biāo)準(zhǔn)目錄結(jié)構(gòu)長這樣src ├── main │ ├── java │ │ └── com/example/demo │ │ ├── DemoApplication.java │ │ ├── controller │ │ ├── service │ │ ├── mapper │ │ └── config │ └── resources │ ├── application.yml │ ├── static │ └── templates └── test └── javaDemoApplication.java就是啟動(dòng)類它上面標(biāo)注了SpringBootApplication。這個(gè)注解是個(gè)組合注解包含了SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。這里有個(gè)大坑啟動(dòng)類必須放在最外層包也就是com.example.demo這個(gè)層級(jí)。因?yàn)镃omponentScan默認(rèn)掃描啟動(dòng)類所在包及其子包如果你把啟動(dòng)類放到controller的上一層之外Spring就掃描不到你的Controller和Service接口全404。3.4 配置文件的核心知識(shí)本地運(yùn)行最重要的配置文件是src/main/resources/application.yml或application.properties。我用YAML格式比較多它層次清晰適合配置較多的場景?；A(chǔ)配置示例server: port: 8080 servlet: context-path: /demo spring: application: name: demo-service datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver這里補(bǔ)充一個(gè)關(guān)鍵原則本地配置永遠(yuǎn)不要和線上配置混在一起。哪怕你圖省事也至少通過Spring Profiles區(qū)分開。方法很簡單application.yml公共配置。application-dev.yml本地開發(fā)環(huán)境配置。application-prod.yml生產(chǎn)環(huán)境配置。啟動(dòng)時(shí)通過spring.profiles.activedev指定激活哪個(gè)環(huán)境。這樣你的本地?cái)?shù)據(jù)庫連接、日志級(jí)別、端口號(hào)都可以和線上保持隔離。我之前接手過一個(gè)項(xiàng)目開發(fā)環(huán)境的數(shù)據(jù)庫密碼直接寫在application.yml里結(jié)果代碼上傳到Git倉庫后密碼泄露——這種教訓(xùn)太普遍了。正確的做法是把敏感配置放到環(huán)境變量或配置中心本地運(yùn)行時(shí)通過SPRING_DATASOURCE_PASSWORD這個(gè)環(huán)境變量注入。4. 本地運(yùn)行與調(diào)試全流程環(huán)境配好了代碼也有了現(xiàn)在來到最關(guān)鍵的一環(huán)把項(xiàng)目跑起來。這里我講兩種方式以及各自適合的場景。4.1 方式一IDEA圖形化運(yùn)行這是最順手的方式也是大多數(shù)開發(fā)者的日常操作。在IDEA中找到主啟動(dòng)類DemoApplication。右鍵點(diǎn)擊選擇Run DemoApplication。觀察底部控制臺(tái)輸出。正常情況下你會(huì)看到Spring的Banner、一堆自動(dòng)裝配的日志最后是Tomcat started on port(s): 8080 (http) with context path Started DemoApplication in 3.2 seconds看到Started關(guān)鍵字說明你的項(xiàng)目已經(jīng)成功啟動(dòng)。但這里有一個(gè)頻率極高的坑第一次啟動(dòng)很可能失敗。最常見的報(bào)錯(cuò)是Port 8080 was already in use。原因很簡單8080端口被其他進(jìn)程占用了。排查方式Windowsnetstat -ano | findstr 8080macOS/Linuxlsof -i:8080找到占用進(jìn)程的PID后殺掉它或者更優(yōu)雅的做法——在application.yml里換一個(gè)端口server: port: 80814.2 方式二Maven命令行運(yùn)行有些人習(xí)慣不用IDE或者在遠(yuǎn)程服務(wù)器上調(diào)試命令行方式就離不開。在項(xiàng)目根目錄執(zhí)行mvn spring-boot:run這個(gè)命令會(huì)先做編譯再啟動(dòng)應(yīng)用。它的好處是和你后續(xù)在CI/CD中用到的命令一致排除了IDE帶來的隱藏差異。比如IDEA有時(shí)會(huì)用自己緩存的舊Class文件導(dǎo)致行為和命令行不一致而命令行永遠(yuǎn)是干凈的。如果你想先跳過測試編譯來加速啟動(dòng)本地調(diào)試時(shí)不建議跑測試太耗時(shí)mvn spring-boot:run -DskipTests如果項(xiàng)目模塊多只想運(yùn)行指定模塊mvn spring-boot:run -pl your-module-name-pl指定模塊路徑后續(xù)還可以加-am讓Maven同時(shí)構(gòu)建其依賴模塊。4.3 打Jar包運(yùn)行偶爾會(huì)遇到需要在本地模擬生產(chǎn)環(huán)境跑的情況這時(shí)就用打包方式mvn clean package -DskipTests指定輸出目錄、跳過測試java -jar target/demo-0.0.1-SNAPSHOT.jar用Jar包方式啟動(dòng)時(shí)如果你在pom.xml中配置了多個(gè)Profile可以用啟動(dòng)參數(shù)指定Profilejava -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.activedev也可以臨時(shí)覆蓋端口java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port8082這一點(diǎn)非常實(shí)用--后面的參數(shù)優(yōu)先級(jí)高于配置文件是Spring Boot配置體系里“命令行參數(shù) Java系統(tǒng)屬性 環(huán)境變量 application.yml”的體現(xiàn)。4.4 熱部署配置本地開發(fā)最讓人煩躁的事情之一就是改一行代碼需要重啟整個(gè)應(yīng)用。Spring Boot官方提供了spring-boot-devtools來解決這個(gè)問題。在pom.xml中添加dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency然后在application.yml里配置spring: devtools: restart: enabled: true原理是devtools監(jiān)控Classpath下的文件變化一旦檢測到變化自動(dòng)重啟應(yīng)用。但要注意重啟不等于熱部署它實(shí)際上是快速重啟不是像JRebel那樣做到方法級(jí)別的熱替換。對(duì)于日常開發(fā)來說快速重啟已經(jīng)能省下大量時(shí)間。我自己習(xí)慣配合IDEA的Build project automatically選項(xiàng)改完代碼按一下CtrlF10或直接切出IDE窗口讓它自動(dòng)構(gòu)建并觸發(fā)重啟。再多配置一步Settings - Advanced Settings - Allow auto-make to start even if developed application is currently running勾上之后體驗(yàn)更好。4.5 遠(yuǎn)程調(diào)試本地運(yùn)行還有一個(gè)容易被忽略但非常實(shí)用的功能遠(yuǎn)程調(diào)試。當(dāng)你在本地啟動(dòng)的應(yīng)用需要和另一個(gè)進(jìn)程比如本地的網(wǎng)關(guān)、另一個(gè)微服務(wù)進(jìn)行聯(lián)調(diào)時(shí)端口級(jí)別的遠(yuǎn)程調(diào)試能幫大忙。在啟動(dòng)命令或IDE的VM options中添加-agentlib:jdwptransportdt_socket,servery,suspendn,address5005然后本地的另一個(gè)IDEA實(shí)例通過Run - Attach to Process連接5005端口就能打斷點(diǎn)調(diào)試了。這個(gè)技能在調(diào)試多模塊項(xiàng)目時(shí)意義很大。5. 常見啟動(dòng)問題與排查實(shí)錄這一節(jié)是全文最有價(jià)值的部分。下面這些坑我全都親手踩過每一個(gè)都花了不少時(shí)間才排查清楚。5.1 依賴沖突先看一個(gè)典型的報(bào)錯(cuò)*************************** APPLICATION FAILED TO START *************************** Description: An attempt was made to call a method that does not exist. The attempt was made from the following location: ...這種問題八成的可能是依賴版本沖突。SpringBoot的自動(dòng)版本管理幫你省了很多事但一旦有某個(gè)依賴你手動(dòng)指定了版本或者某個(gè)傳遞依賴和SpringBoot內(nèi)置版本不一致就會(huì)出現(xiàn)這種情況。排查步驟執(zhí)行mvn dependency:tree看依賴樹。搜索沖突的GAVGroupId、ArtifactId、Version。用mvn dependency:analyze檢查無用依賴和缺失依賴。比如常見的spring-boot-starter-data-redis底層引入了lettuce-core如果你想用Jedis就必須排除lettuce添加jedis依賴。不排除就會(huì)導(dǎo)致兩個(gè)Redis客戶端共存行為怪異的很。5.2 自動(dòng)配置類報(bào)錯(cuò)Description: Failed to configure a DataSource: url attribute is not specified and no embedded datasource could be configured. Reason: Failed to determine a suitable driver class如果你只是引入spring-boot-starter-data-jpa或mybatis-spring-boot-starter但沒有配置數(shù)據(jù)庫連接信息啟動(dòng)時(shí)就會(huì)報(bào)這個(gè)錯(cuò)。原因在于SpringBoot自動(dòng)裝配嘗試創(chuàng)建DataSource實(shí)例但沒有拿到連接信息。解決方案也簡單如果暫時(shí)不需要數(shù)據(jù)庫操作把對(duì)應(yīng)依賴從pom.xml中移除?；蛘呓oSpringBootApplication加一個(gè)排除屬性SpringBootApplication(exclude {DataSourceAutoConfiguration.class})這個(gè)排除操作僅建議在臨時(shí)調(diào)試時(shí)使用真正開發(fā)時(shí)還是老老實(shí)實(shí)配上數(shù)據(jù)源。5.3 include相關(guān)漏配導(dǎo)致的404項(xiàng)目能啟動(dòng)但訪問接口是404。這種情況很迷惑人因?yàn)轫?xiàng)目看起來一切正常。排查思路按照從外到內(nèi)確認(rèn)訪問路徑是否正確context-path有沒有配RequestMapping的路徑對(duì)不對(duì)確認(rèn)Controller是否被掃描到檢查啟動(dòng)類是否在包的頂層。確認(rèn)RestController還是Controller如果是Controller接口方法返回字符串時(shí)可能會(huì)被Spring MVC當(dāng)作視圖名處理而不是直接返回內(nèi)容導(dǎo)致響應(yīng)內(nèi)容和預(yù)期不符。5.4 編碼問題導(dǎo)致的亂碼中文亂碼在本地運(yùn)行中很常見分兩種控制臺(tái)亂碼和響應(yīng)亂碼?？刂婆_(tái)亂碼多半是IDEA控制臺(tái)編碼和項(xiàng)目編碼不一致。設(shè)置里把File Encodings全部調(diào)整為UTF-8同時(shí)修改IDEA安裝目錄bin下的idea64.exe.vmoptions文件加上-Dfile.encodingUTF-8響應(yīng)亂碼則可能是你返回的字符串在HTTP傳輸時(shí)編碼問題。SpringBoot默認(rèn)已經(jīng)設(shè)置為UTF-8但如果你在代碼中手動(dòng)處理了字節(jié)流或者用了舊的HttpMessageConverter就可能踩坑。最簡單的排查方式是在application.yml中顯式聲明server: servlet: encoding: charset: UTF-8 enabled: true force: true5.5 內(nèi)存溢出本地跑大型項(xiàng)目時(shí)JVM默認(rèn)堆內(nèi)存太小容易崩潰。IDEA默認(rèn)的堆內(nèi)存設(shè)置往往不夠用如果你看到j(luò)ava.lang.OutOfMemoryError: Java heap space或干脆應(yīng)用進(jìn)程被殺。處理方式是在運(yùn)行配置中調(diào)整VM options-Xms512m -Xmx2048m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m如果你的項(xiàng)目編譯很重、依賴特別多Metaspace可以適當(dāng)調(diào)大一些。順手建議把-XX:HeapDumpOnOutOfMemoryError加上JVM可以在崩潰時(shí)導(dǎo)出堆轉(zhuǎn)儲(chǔ)文件方便排查內(nèi)存泄漏。5.6 配置文件未生效你改了application.yml里的端口重啟后還是8080。這種問題很詭異最常見的原因是配置文件根本沒被加載。檢查文件是否在src/main/resources目錄下。文件名是否是application.yml或application-{profile}.yml。是否同時(shí)在application.properties和application.yml中配置了同一屬性——如果兩個(gè)文件都存在application.properties優(yōu)先級(jí)高于application.yml你改YAML文件當(dāng)然不生效。命令行是否有--server.port參數(shù)覆蓋了配置文件。5.7 端口被占用速查表用一張表做個(gè)總結(jié)以后遇到端口問題直接對(duì)照排查報(bào)錯(cuò)信息原因解決方案Port 8080 was already in use端口被其他進(jìn)程占用殺進(jìn)程或換端口Address already in use網(wǎng)絡(luò)地址被占用可能是Socket未釋放lsof -i:端口找PID殺掉Error creating bean with name tomcatServletWebServerFactory端口綁定失敗檢查是否有特權(quán)端口小于1024Web server failed to start. Port X was already in use同上在配置文件中更換端口5.8 Lombok依賴問題Lombok是SpringBoot項(xiàng)目里很常見的依賴但它有個(gè)特點(diǎn)必須在編譯期通過注解處理器生成代碼。如果你啟動(dòng)時(shí)報(bào)各種getter/setter找不到或者java: package lombok does not exist大概率是Lombok版本和JDK版本不兼容。JDK 8 Lombok 1.18.20及以下正常。JDK 11需要Lombok 1.18.20以上。JDK 17需要Lombok 1.18.24以上。JDK 21需要Lombok 1.18.30以上。同時(shí)IDEA的Settings - Build - Compiler - Annotation Processors勾選Enable annotation processing。這步漏了IDEA里會(huì)瘋狂報(bào)找不到符號(hào)。5.9 多模塊項(xiàng)目的本地運(yùn)行微服務(wù)項(xiàng)目在本地運(yùn)行時(shí)經(jīng)常會(huì)出現(xiàn)跨模塊聯(lián)調(diào)問題。典型場景A服務(wù)調(diào)用B服務(wù)B沒啟動(dòng)A服務(wù)報(bào)連接拒絕。排查思路確認(rèn)B服務(wù)的地址和端口是否配置正確。確認(rèn)A服務(wù)的注冊(cè)中心如Nacos、Eureka是否可達(dá)。如果走的是Feign/OpenFeign檢查超時(shí)時(shí)間和熔斷配置。這里有個(gè)小技巧本地調(diào)試時(shí)可以把注冊(cè)中心的配置指向本地啟動(dòng)的Nacos只啟動(dòng)需要的兩個(gè)服務(wù)其他的服務(wù)都關(guān)掉效率高很多。6. 進(jìn)階技巧與最佳實(shí)踐6.1 啟動(dòng)參數(shù)里的SpringApplication.run有人會(huì)有疑問cmd上能不能省掉--前綴實(shí)際上SpringBoot命令行參數(shù)有兩種寫法java -jar app.jar --server.port8081 java -jar app.jar -Dserver.port8081第一種寫法是SpringBoot命名的參數(shù)--第二種是JVM系統(tǒng)屬性-D。兩者都能生效但優(yōu)先級(jí)不同--參數(shù)優(yōu)先級(jí)更高。如果你發(fā)現(xiàn)配置文件改了不生效先看看啟動(dòng)命令里是不是有這兩種參數(shù)在“強(qiáng)覆蓋”。6.2 啟動(dòng)時(shí)的Banner優(yōu)化SpringBoot默認(rèn)啟動(dòng)時(shí)會(huì)在控制臺(tái)打印一個(gè)大大的“Spring”字符畫。如果你覺得太占地方或者想在日志里標(biāo)記一下版本信息可以在src/main/resources下放一個(gè)banner.txtSpringBoot會(huì)自動(dòng)識(shí)別。網(wǎng)上還有Banner生成器能生成特定字符圖案團(tuán)隊(duì)內(nèi)部用這個(gè)小細(xì)節(jié)來標(biāo)識(shí)環(huán)境dev/test/prod還挺有用。關(guān)閉Banner也很簡單SpringApplication app new SpringApplication(DemoApplication.class); app.setBannerMode(Banner.Mode.OFF); app.run(args);6.3 日志級(jí)別的本地調(diào)整排查問題時(shí)把日志級(jí)別臨時(shí)調(diào)低是最有效的調(diào)試手段之一。logging: level: root: info com.example.demo.mapper: debug這樣配置后MyBatis的SQL日志會(huì)完整打印在控制臺(tái)本地調(diào)試效率提升非常明顯。但記得排查完改回去別把debug級(jí)別的日志帶上生產(chǎn)。6.4 Docker Desktop本地運(yùn)行SpringBoot不少團(tuán)隊(duì)會(huì)用Docker Desktop在本地模擬生產(chǎn)環(huán)境運(yùn)行SpringBoot。這里有個(gè)小坑先構(gòu)建Jar包再寫Dockerfile。如果你依賴遠(yuǎn)程私有倉庫構(gòu)建Docker鏡像時(shí)還需要考慮網(wǎng)絡(luò)問題。最精簡的DockerfileFROM openjdk:8-jdk-alpine COPY target/demo-0.0.1-SNAPSHOT.jar app.jar ENTRYPOINT [java,-jar,/app.jar]如果JDK版本是17基礎(chǔ)鏡像用eclipse-temurin:17-jdk。用Docker啟動(dòng)時(shí)端口映射和文件掛載是高頻出錯(cuò)的點(diǎn)docker run -d -p 8080:8080 -v /path/to/config:/config --env SPRING_PROFILES_ACTIVEdev demo-image6.5 從崩潰到定位的十分鐘排查路徑最后分享一套我自己的本地運(yùn)行故障排查路徑效率極高看啟動(dòng)日志定位第一個(gè)ERROR級(jí)別的堆棧不要從上往下全看而是從下往上找Caused by。確認(rèn)Spring Boot版本和JDK版本是否匹配。執(zhí)行mvn clean清掉舊的編譯產(chǎn)物再重新構(gòu)建。這一步能解決大量“奇怪”問題。檢查配置項(xiàng)是否被Profile覆蓋。如果涉及多個(gè)服務(wù)確認(rèn)依賴服務(wù)的健康狀態(tài)。這套路徑我稱之為“從啟動(dòng)到定位的十分鐘”核心思想是從日志倒推從環(huán)境入手先排除掉最基礎(chǔ)的構(gòu)建問題再去分析業(yè)務(wù)代碼。按這個(gè)順序排查大部分啟動(dòng)故障都能在十分鐘內(nèi)定位到根因。7. 一點(diǎn)個(gè)人的經(jīng)驗(yàn)心得做SpringBoot本地運(yùn)行這件事看起來簡單但真正絲滑地跑起來靠的是對(duì)環(huán)境、構(gòu)建、配置、調(diào)試這四件事的深度理解。我在工作中見過太多人卡在環(huán)境問題上有人JDK版本配錯(cuò)了沒發(fā)現(xiàn)有人Maven鏡像配錯(cuò)了拉不下來依賴有人配置文件里寫錯(cuò)了縮進(jìn)導(dǎo)致屬性沒生效還有人因?yàn)镮DEA緩存問題浪費(fèi)了一下午。我的建議很簡單把環(huán)境當(dāng)代碼一樣管理。用工具鏈固定JDK版本用settings.xml統(tǒng)一Maven配置用Profile隔離每個(gè)環(huán)境的配置把啟動(dòng)和調(diào)試的每一步都做成可重復(fù)的腳本。這樣無論你換多少個(gè)項(xiàng)目、多少臺(tái)電腦都能在十分鐘內(nèi)把項(xiàng)目跑起來。另外遇到問題多看一眼啟動(dòng)日志的Caused by部分那才是真正的病因。