寫Java Web的程序員大概率都經(jīng)歷過這樣一個場景本地IDE里跑得好好的接口一到終端環(huán)境就404折騰半天發(fā)現(xiàn)是war包沒打?qū)蛘呤莣eb.xml漏了一行配置。Servlet部署這件事代碼寫得再漂亮最后都要落到“怎么把應(yīng)用正確裝進Tomcat”這一步。這篇教程就從零開始把Servlet基于Tomcat部署的完整流程、底層原理、還有我踩過的坑一次講清楚。適合誰看剛學(xué)完Java SE、準備進入Java Web階段的同學(xué)或者在工作中需要維護老項目、偶爾要手動部署應(yīng)用的開發(fā)。不管你用的是IDE還是純命令行看完之后都能手動完成一個Servlet從編譯、打包到部署的全流程。我盡量不講多余的理論每一步都給你能直接照抄的操作。1. Servlet和Tomcat分別是什么為什么部署的不是“一個類”1.1 Servlet本質(zhì)是一套規(guī)范很多初學(xué)者會把Servlet理解成一個類覺得寫一個繼承了HttpServlet的類它就是Servlet了。這么說不準確。Servlet本身是Java EE后來叫Jakarta EE定義的一套接口規(guī)范規(guī)定了服務(wù)器端如何處理HTTP請求、如何響應(yīng)客戶端。你寫的那個類本質(zhì)上是這套規(guī)范的一個具體實現(xiàn)。用一個生活化的類比。Servlet規(guī)范就像餐飲行業(yè)的衛(wèi)生標準你開一家飯店就是實現(xiàn)了這套標準。但光有你的飯店還不行你還得租在一個商場里才能正常營業(yè)。這個“商場”就是Tomcat。1.2 Tomcat的角色Servlet容器Tomcat是一個Servlet容器也叫Web容器它負責(zé)兩件核心的事管理Servlet的生命周期處理底層HTTP網(wǎng)絡(luò)通信。你寫的Servlet類編譯之后就是一個普通class文件它自己不會監(jiān)聽端口不會解析HTTP報文更不會處理并發(fā)請求。Tomcat把這些底層工作全部接管了。當(dāng)請求進來Tomcat根據(jù)URL定位到對應(yīng)的Servlet判斷該實例化還是復(fù)用已有實例然后調(diào)用service方法最后再把響應(yīng)寫回客戶端。Servlet只管業(yè)務(wù)邏輯剩下的臟活累活都是容器干的。這個“容器”身份很關(guān)鍵后面在排查一些類加載、實例化異常時你都會反復(fù)用到這個認知。1.3 部署的本質(zhì)是什么明白了上面兩點“部署”這個詞就好理解了。部署的本質(zhì)就是把你的class文件、依賴的jar包、配置文件按照容器能識別的目錄結(jié)構(gòu)組織起來放到Tomcat指定的位置讓它能加載并執(zhí)行。Tomcat在啟動的時候會掃描這些位置解析配置把Servlet實例化并注冊到映射表里。映射表就是“哪個URL對應(yīng)哪個類”的一份記錄web.xml里配的servlet-mapping干的就是這件事。很多同學(xué)部署失敗就是因為不理解“目錄結(jié)構(gòu)是約定”。Tomcat不會智能地去找你的類它只認它約定的那套結(jié)構(gòu)。war包為什么能一鍵部署因為它本質(zhì)上就是把約定好的目錄結(jié)構(gòu)壓縮成一個文件Tomcat解壓之后就能直接識別。2. 環(huán)境準備與版本矩陣先把手里的牌理清楚2.1 JDK版本怎么選部署Servlet項目第一步是確認JDK版本。不同版本的Servlet規(guī)范、Tomcat版本對JDK的要求不一樣。我給的推薦原則是生產(chǎn)環(huán)境用穩(wěn)定版本新項目用LTS版本。當(dāng)前環(huán)境下JDK 8和JDK 11仍然大量存在JDK 17也已經(jīng)非常主流。如果這個項目要跑在別人的老服務(wù)器上先問清楚對方的Java版本再決定用哪個版本編譯。編譯版本如果高于服務(wù)器運行版本啟動或運行時會直接報UnsupportedClassVersionError這個錯誤信息里會帶上版本號看到它基本就能定位。我自己的習(xí)慣是新項目統(tǒng)一用JDK 17本地開發(fā)和生產(chǎn)環(huán)境保持一致。老項目維護則看對方服務(wù)器跑的是什么不輕易升級。2.2 Tomcat版本和Servlet版本怎么對應(yīng)Tomcat的版本號和Servlet/JSP規(guī)范版本有對應(yīng)關(guān)系。簡單記幾個常用的Tomcat版本對應(yīng)Servlet規(guī)范Servlet包名Tomcat 8.5Servlet 3.1javax.servletTomcat 9.xServlet 4.0javax.servletTomcat 10.0.xServlet 5.0jakarta.servletTomcat 10.1.xServlet 6.0jakarta.servlet這是我們最常遇到的一個坑。Tomcat 10之后包名從javax.servlet換成了jakarta.servlet。如果你還用javax.servlet的包名去寫代碼本地編譯能過因為本地引的是舊版servlet-api一部署到Tomcat 10上就報ClassNotFoundException。所以自己搭環(huán)境的時候建議先用Tomcat 9用javax.servlet包名網(wǎng)上大多數(shù)老教程的代碼都能直接跑。如果你用Tomcat 10就要注意引入的是jakarta.servlet-api代碼里的import也要改成jakarta開頭的包名。2.3 Tomcat目錄結(jié)構(gòu)要先看懂Tomcat解壓之后的主要目錄以Tomcat 9為例bin啟動和關(guān)閉腳本conf核心配置server.xml、web.xml都在這里libTomcat自身的庫servlet-api.jar就在里面logs日志輸出webapps應(yīng)用部署目錄war包放這里workJSP編譯后的臨時文件目錄webapps是部署最相關(guān)的目錄后面的實操主要就圍繞它。另外conf/server.xml里有連接器的配置端口就在這里改。默認是8080如果被占用了可以改但不建議輕易亂改因為改了之后別人的腳本、監(jiān)控、防火墻規(guī)則可能就全部對不上了。3. 從零寫一個Servlet并完成一次完整部署3.1 手工創(chuàng)建工程結(jié)構(gòu)這一步不需要任何IDE先用命令行把項目搭出來。這一步走通了你就能理解IDE背后幫你做的事。deploy-demo ├── src │ └── com │ └── example │ └── demo │ └── HelloServlet.java ├── web │ ├── WEB-INF │ │ └── web.xml │ └── index.html └── lib說明一下這個結(jié)構(gòu)的用意src存放Java源文件按包結(jié)構(gòu)組織。web是Web應(yīng)用的根目錄WEB-INF必須放在這里web.xml也必須在WEB-INF下。lib目錄是給項目自己的依賴jar包用的比如連接數(shù)據(jù)庫的驅(qū)動。WEB-INF這個目錄比較特殊它里面的內(nèi)容對瀏覽器不可見是給Tomcat用的。配置文件放這里外部用戶無法直接訪問安全性上有保障。很多人剛學(xué)的時候把Java文件直接丟在web目錄下Tomcat根本不會去編譯也不會執(zhí)行因為沒有class文件可加載。3.2 寫一個最簡單的Servlet我寫一個HelloServlet處理GET請求輸出一行HTML。package com.example.demo; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(h1Hello, Servlet deployed on Tomcat!/h1); } Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { doGet(req, resp); } }注意到doGet方法里我把響應(yīng)類型設(shè)置成了text/html并且指定了charsetUTF-8。這一步很多人會漏漏了的結(jié)果就是瀏覽器里中文全變成亂碼。后面問題排查部分還會再講。如果項目用的是Tomcat 10只需要把代碼里的javax全部替換成jakarta邏輯完全一樣。3.3 配置web.xml告訴Tomcat路由規(guī)則光有類還不行Tomcat不知道這個類對應(yīng)哪個URL必須在web.xml里聲明。web.xml是Servlet規(guī)范里約定的部署描述文件容器啟動時會解析它。?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 display-nameDeployDemo/display-name servlet servlet-namehello/servlet-name servlet-classcom.example.demo.HelloServlet/servlet-class load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namehello/servlet-name url-pattern/hello/url-pattern /servlet-mapping /web-app這里面有三個點要講清楚。第一servlet-name是邏輯名servlet-class才是全限定類名映射的時候通過邏輯名關(guān)聯(lián)。兩個name必須完全一致寫錯大小寫、多個空格都不行。第二url-pattern就是瀏覽器訪問的路徑。配了/hello之后通過http://localhost:8080/應(yīng)用名/hello就能訪問到這個Servlet。url-pattern的寫法要符合Servlet規(guī)范比如/開頭的路徑或者*.do這樣的擴展名映射不能隨便寫。第三load-on-startup表示是否在Tomcat啟動時就實例化這個Servlet。默認是第一次訪問時才實例化懶加載配了數(shù)字之后數(shù)字越小越先加載。生產(chǎn)環(huán)境里初始化比較重的Servlet建議配置這個屬性啟動時完成初始化避免第一個用戶訪問時等很久。3.4 編譯注意classpath要帶上servlet-api編譯類的操作很簡單但是classpath必須包含servlet-api.jar否則編譯報錯找不到HttpServlet。javac -encoding UTF-8 \ -classpath /path/to/tomcat/lib/servlet-api.jar \ -d web/WEB-INF/classes \ src/com/example/demo/HelloServlet.java-d參數(shù)指定class文件的輸出目錄。我直接輸出到了web/WEB-INF/classes這是Tomcat約定的一個“類搜索路徑”class文件放在這里Tomcat啟動時就能根據(jù)全限定名找到。為什么要加encoding參數(shù)Windows平臺的默認編碼可能是GBK源文件如果本身是UTF-8編譯時不指定-encoding中文字符串在運行時就可能出現(xiàn)亂碼甚至編譯報錯。這個參數(shù)平時不顯眼在跨平臺部署時能省掉很多麻煩。3.5 打包成war包編譯完成之后整個web目錄就是一個標準的Web應(yīng)用目錄結(jié)構(gòu)。要把它部署到Tomcat最標準的做法是打包成war包。war包本質(zhì)就是jar包格式只不過約定好了里面的內(nèi)容是一個Web應(yīng)用。在web目錄的上一級執(zhí)行jar cvf deploy-demo.war -C web .這條命令的意思是把web目錄下的所有內(nèi)容打包deploy-demo.war就生成了。注意-C先進入web目錄再打包確保war包內(nèi)的路徑是以根開始而不是帶一級“web”路徑。否則Tomcat解壓之后會多一層web目錄訪問路徑就變了。打出來的war包可以用jar tf deploy-demo.war確認里面結(jié)構(gòu)是否正確重點看WEB-INF/classes/com/example/demo/HelloServlet.class和WEB-INF/web.xml是否在正確位置。3.6 部署到Tomcat兩種方式方式一把war包直接拷貝到webapps目錄。cp deploy-demo.war /path/to/tomcat/webapps/ cd /path/to/tomcat/bin ./startup.sh # Windows下是 startup.batTomcat啟動時會自動掃描webapps下的war包把它解壓到同名的目錄deploy-demo。然后訪問http://localhost:8080/deploy-demo/hello就能看到瀏覽器輸出“Hello, Servlet deployed on Tomcat!”。方式二開發(fā)期直接把目錄拷過去。如果沒有打war包也可以把整個web目錄改名為應(yīng)用名后拷貝到webapps下同時保留WEB-INF結(jié)構(gòu)。cp -r web /path/to/tomcat/webapps/deploy-demo這種方式在開發(fā)階段非常方便。改完Java代碼重新編譯覆蓋class文件刷新瀏覽器就能看到效果不需要重啟Tomcat。我做日常調(diào)試時經(jīng)常用這個方法省時間。3.7 驗證三個關(guān)鍵點部署完了一定要驗證而且要按順序驗證。第一看Tomcat啟動日志有沒有報錯。日志在logs目錄下catalina.out記錄了啟動過程如果有異?；灸軓倪@里看到。特別是SEVERE級別的日志基本就是部署失敗的原因。第二確認war解壓成功?？磜ebapps下是否生成了deploy-demo目錄。如果war包損壞Tomcat會解壓失敗此時訪問必404。第三訪問URL是否正確。上下文路徑是war包文件名所以war包名叫deploy-demo.war訪問路徑就是/deploy-demo。如果你把它改成demo.war路徑就變成/demo/hello。改文件名會直接影響URL這個要特別注意。4. 部署背后的工作細節(jié)Tomcat怎么加載你的應(yīng)用4.1 應(yīng)用上下文Context是什么Tomcat把每個Web應(yīng)用稱為一個Context。webapps下一個war包啟動后對應(yīng)一個Contextcontext路徑默認就是war包名不含.war后綴。這個路徑?jīng)Q定了URL的第一段。如果想把應(yīng)用部署在根路徑訪問時直接http://localhost:8080/hello需要把war包改名為ROOT.war。這是Tomcat內(nèi)置的默認Web應(yīng)用約定。注意大小寫ROOT不能寫成root我見過幾次因為文件命名不規(guī)范導(dǎo)致部署無效頁面怎么都訪問不到。4.2 WAR包解壓機制Tomcat在啟動掃描到war包時會把它自動解壓到同名目錄。下次啟動時如果發(fā)現(xiàn)同名目錄已經(jīng)存在并且war包沒有更新就不會重新解壓。這個機制帶來一個很實用的技巧更新應(yīng)用時直接拷貝新的war包覆蓋但一定要記得先刪除舊的解壓目錄否則可能出現(xiàn)新代碼沒有生效的情況。這個“明明改了代碼、運行還是舊的”的情況我排查過很多次十有八九是解壓目錄沒有清干凈。work目錄下的臨時文件同理JSP修改后沒有重新編譯時也可以清一下work目錄。4.3 不部署war包的另一種方式Context描述文件如果你的應(yīng)用不想放在webapps下還可以在conf/Catalina/localhost下放一個context描述文件指向任意磁盤路徑。比如創(chuàng)建conf/Catalina/localhost/demo.xml內(nèi)容如下Context docBase/data/webapp/deploy-demo path/demo /這樣配置之后Tomcat會把/data/webapp/deploy-demo這個目錄加載為一個Context訪問路徑/demo就指向這個應(yīng)用。這個方式在生產(chǎn)環(huán)境里比較常用應(yīng)用放在磁盤指定位置日志、數(shù)據(jù)目錄也相對集中升級時不需要動Tomcat目錄。注意path屬性在較新的Tomcat版本中可能被忽略實際路徑以文件名為主。也就是說文件叫demo.xml上下文路徑就是/demo。這個細節(jié)很多人不知道配置了半天發(fā)現(xiàn)路徑不對其實就是文件命名問題。4.4 為什么訪問頁面卻看到404404這個狀態(tài)碼在Servlet部署場景里有兩個高頻原因。一是上下文路徑輸錯了。比如war包叫demo.war你訪問的時候?qū)懗闪薲eploy-demo。這個錯誤很常見尤其是部署了多個版本的歷史war包時。二是應(yīng)用根本沒有成功加載。Tomcat啟動時如果加載失敗應(yīng)用不會啟動訪問自然404。排查看日志是最快的路徑不要只盯著瀏覽器。Tomcat啟動時如果加載失敗日志里的異常堆棧會直接告訴你問題在哪比如web.xml解析失敗、類沒有找到。5. 常見問題與排查技巧實錄5.1 高頻問題速查表這一部分是我在幫別人排錯時遇到的高頻問題整理成一個速查表按現(xiàn)象、原因、處理辦法來組織。問題現(xiàn)象可能原因處理辦法訪問返回404上下文路徑寫錯核對war包名和URL路徑訪問返回404web.xml映射錯誤檢查servlet-mapping的url-pattern和servlet-name訪問返回500Servlet代碼拋異?？碿atalina.out日志堆棧ClassNotFoundExceptionTomcat版本與包名不匹配Tomcat 10用jakarta.servlet9用javax.servletUnsupportedClassVersionError編譯版本高于運行版本用與服務(wù)器JDK匹配的版本重新編譯頁面中文亂碼響應(yīng)未設(shè)置charset在response設(shè)置ContentType或統(tǒng)一配置編碼Filter端口被占用其他進程占用了8080換端口或停掉占用進程更新的代碼不生效舊解壓目錄未清理刪除webapps下解壓目錄后重啟依賴類找不到第三方j(luò)ar包沒有打進war把jar放到WEB-INF/lib目錄5.2 幾個重點問題的排查現(xiàn)場端口占用這個問題很常見。Linux下用lsof -i:8080查占用情況Windows下用netstat -ano | findstr 8080。定位到PID之后確認不是關(guān)鍵進程再處理。如果你只是本地測試也可以直接改conf/server.xml里的Connector端口改成8081重啟即可。但改了端口所有訪問路徑都要跟著改這點要記住。類找不到的問題最大的坑是Tomcat版本和Servlet包名不匹配。Tomcat 10把javax.servlet全面換成jakarta.servlet老代碼直接部署必掛。新項目建議一上來就用Tomcat 10用jakarta包名后面升級不會有這個問題。舊項目如果是跑在Tomcat 9上就保持javax不動。還有一個很多人會踩的坑把自己項目的lib目錄里放了servlet-api.jar再部署結(jié)果啟動報重復(fù)類定義錯誤。servlet-api.jar是容器提供的不要在應(yīng)用里帶否則會出現(xiàn)類沖突。Tomcat的類加載機制是“父委托”應(yīng)用目錄里的類會優(yōu)先被加載放一個舊版本進去反而會把容器自己的版本屏蔽掉導(dǎo)致各種莫名的NoSuchMethodError。編碼問題的重災(zāi)區(qū)是Windows環(huán)境。一個項目里源文件是UTF-8跳轉(zhuǎn)頁面是GBK響應(yīng)頭里又沒設(shè)置charset出來的中文必亂碼。建議大家統(tǒng)一用UTF-8源文件、配置文件、數(shù)據(jù)庫連接URL、響應(yīng)ContentType全部統(tǒng)一亂碼問題能減少九成。5.3 看日志的正確姿勢很多人部署失敗之后第一反應(yīng)是問我我就反問一句日志看了沒看日志是排查的第一步也是基本功。Tomcat日志主要在logs目錄下。catalina.out是主日志啟動過程、應(yīng)用加載、異常堆棧都在這里。localhost.log記錄Web應(yīng)用初始化相關(guān)信息部署失敗的關(guān)鍵信息經(jīng)常在這里。還有l(wèi)ocalhost_access_log開頭的文件記錄訪問日志排查請求有沒有到達Tomcat非常有用。當(dāng)你訪問頁面返回404先去看localhost_access_log確認請求到底有沒有進來。如果日志里根本沒有這個請求那問題可能出在端口、防火墻、上下文路徑。如果有請求但返回404再看是不是應(yīng)用沒加載?？慈罩静皇窍箍匆磿r間順序看從啟動的第一行看到最后一行重點關(guān)注第一次出現(xiàn)ERROR或SEVERE的位置那往往就是根因所在。6. 部署優(yōu)化與自動化建議6.1 用構(gòu)建工具替換手工打包手工流程走一遍是為了理解原理但真正上了項目還用命令行打包就太累了。建議用Maven或Gradle管理項目。Maven項目的pom.xml里打包插件配置好之后mvn clean package就能直接生成war包。war包名稱可以用finalName控制避免默認帶版本號導(dǎo)致上下文路徑變化。build finalNamedeploy-demo/finalName plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-war-plugin/artifactId version3.3.2/version /plugin /plugins /build這里有個非常實用的經(jīng)驗war包名一旦定下來就不要隨便改。每次構(gòu)建生成固定名字的war部署腳本和監(jiān)控腳本都依賴這個路徑。如果maven每次都生成帶版本號的包比如deploy-demo-1.0.0.war那么上下文路徑就會變成/deploy-demo-1.0.0訪問地址跟著變發(fā)布腳本也要跟著改很痛苦。6.2 自動化部署與健康檢查發(fā)布頻率高了之后人肉拷貝不是辦法可以寫一個簡單腳本。bash腳本的核心邏輯大概是這樣的備份舊war包拷貝新war包刪除舊解壓目錄啟動Tomcat然后循環(huán)探測健康檢查URL。#!/bin/bash APP_NAMEdeploy-demo TOMCAT_HOME/opt/tomcat WAR_FILEtarget/${APP_NAME}.war # 1. 停掉Tomcat ${TOMCAT_HOME}/bin/shutdown.sh # 2. 清理舊版本 rm -rf ${TOMCAT_HOME}/webapps/${APP_NAME}* cp ${WAR_FILE} ${TOMCAT_HOME}/webapps/ # 3. 啟動 ${TOMCAT_HOME}/bin/startup.sh # 4. 輪詢探測應(yīng)用是否啟動成功 for i in $(seq 1 30); do if curl -s http://localhost:8080/${APP_NAME}/hello | grep -q Hello; then echo Deploy success exit 0 fi sleep 2 done echo Deploy failed, check logs exit 1注意腳本里curl探測的是具體業(yè)務(wù)頁面而不是只看Tomcat端口通不通。因為Tomcat進程起來了不代表應(yīng)用加載成功。有時候應(yīng)用初始化失敗Tomcat照樣監(jiān)聽8080但訪問應(yīng)用頁面就是404。用業(yè)務(wù)URL做健康檢查可以避免這個假象。6.3 部署環(huán)境盡量保持一致Java Web項目在跨環(huán)境時最容易出問題的就是JDK版本、Tomcat版本、配置文件這三者。版本不一致很多詭異問題根本不會發(fā)生一旦發(fā)生就很難解釋。我建議本地開發(fā)、測試環(huán)境、生產(chǎn)環(huán)境統(tǒng)一用一個Tomcat版本至少是一個大版本。比如全部用Tomcat 9.0.x而不是這邊用8.5那邊用9.0。JDK也一樣不要本地17、服務(wù)器8這么混搭。配置文件這塊數(shù)據(jù)庫連接配置盡量通過環(huán)境變量或外部配置文件注入不要寫死在代碼里。這樣部署腳本只需要維護一套模板不同環(huán)境替換環(huán)境變量就行。還有最后一個經(jīng)驗部署之前確認一個干凈的Tomcat實例。試過很多次一個跑過多個項目的Tomcatconf目錄里改過的配置可能已經(jīng)被上一個項目玩壞了與其仔細排查不如直接解壓一個新Tomcat一次到位。結(jié)尾我個人在實際操作中的體會是Servlet部署不難難在理解Tomcat的工作方式。把webapps目錄、Context、WEB-INF、war解壓這幾個概念真正理解透遇到問題就有基本的排查思路。很多人卡在404上一下午就是因為不知道Tomcat有日志這回事也不知道上下文路徑和war包名的對應(yīng)關(guān)系。最后再分享一個小技巧如果你只是想快速驗證Tomcat環(huán)境干不干凈可以用Tomcat自帶的examples應(yīng)用。訪問一下http://localhost:8080/examples/能打開說明容器本身沒問題接下來再排查你自己的應(yīng)用配置。這個技巧幫我省掉過很多次無謂的懷疑。掌握了這里面的原理之后后面再學(xué)Spring Boot的內(nèi)嵌容器你會發(fā)現(xiàn)很多思想是相通的。內(nèi)嵌Tomcat無非是把容器搬進了應(yīng)用里但還是同一套Servlet規(guī)范的底層邏輯。所以說Servlet部署這個基本功值得認真過一遍。 Servlet部署到Tomcat全流程：從war包到web.xml的實踐指南
寫Java Web的程序員大概率都經(jīng)歷過這樣一個場景本地IDE里跑得好好的接口一到終端環(huán)境就404折騰半天發(fā)現(xiàn)是war包沒打?qū)蛘呤莣eb.xml漏了一行配置。Servlet部署這件事代碼寫得再漂亮最后都要落到“怎么把應(yīng)用正確裝進Tomcat”這一步。這篇教程就從零開始把Servlet基于Tomcat部署的完整流程、底層原理、還有我踩過的坑一次講清楚。適合誰看剛學(xué)完Java SE、準備進入Java Web階段的同學(xué)或者在工作中需要維護老項目、偶爾要手動部署應(yīng)用的開發(fā)。不管你用的是IDE還是純命令行看完之后都能手動完成一個Servlet從編譯、打包到部署的全流程。我盡量不講多余的理論每一步都給你能直接照抄的操作。1. Servlet和Tomcat分別是什么為什么部署的不是“一個類”1.1 Servlet本質(zhì)是一套規(guī)范很多初學(xué)者會把Servlet理解成一個類覺得寫一個繼承了HttpServlet的類它就是Servlet了。這么說不準確。Servlet本身是Java EE后來叫Jakarta EE定義的一套接口規(guī)范規(guī)定了服務(wù)器端如何處理HTTP請求、如何響應(yīng)客戶端。你寫的那個類本質(zhì)上是這套規(guī)范的一個具體實現(xiàn)。用一個生活化的類比。Servlet規(guī)范就像餐飲行業(yè)的衛(wèi)生標準你開一家飯店就是實現(xiàn)了這套標準。但光有你的飯店還不行你還得租在一個商場里才能正常營業(yè)。這個“商場”就是Tomcat。1.2 Tomcat的角色Servlet容器Tomcat是一個Servlet容器也叫Web容器它負責(zé)兩件核心的事管理Servlet的生命周期處理底層HTTP網(wǎng)絡(luò)通信。你寫的Servlet類編譯之后就是一個普通class文件它自己不會監(jiān)聽端口不會解析HTTP報文更不會處理并發(fā)請求。Tomcat把這些底層工作全部接管了。當(dāng)請求進來Tomcat根據(jù)URL定位到對應(yīng)的Servlet判斷該實例化還是復(fù)用已有實例然后調(diào)用service方法最后再把響應(yīng)寫回客戶端。Servlet只管業(yè)務(wù)邏輯剩下的臟活累活都是容器干的。這個“容器”身份很關(guān)鍵后面在排查一些類加載、實例化異常時你都會反復(fù)用到這個認知。1.3 部署的本質(zhì)是什么明白了上面兩點“部署”這個詞就好理解了。部署的本質(zhì)就是把你的class文件、依賴的jar包、配置文件按照容器能識別的目錄結(jié)構(gòu)組織起來放到Tomcat指定的位置讓它能加載并執(zhí)行。Tomcat在啟動的時候會掃描這些位置解析配置把Servlet實例化并注冊到映射表里。映射表就是“哪個URL對應(yīng)哪個類”的一份記錄web.xml里配的servlet-mapping干的就是這件事。很多同學(xué)部署失敗就是因為不理解“目錄結(jié)構(gòu)是約定”。Tomcat不會智能地去找你的類它只認它約定的那套結(jié)構(gòu)。war包為什么能一鍵部署因為它本質(zhì)上就是把約定好的目錄結(jié)構(gòu)壓縮成一個文件Tomcat解壓之后就能直接識別。2. 環(huán)境準備與版本矩陣先把手里的牌理清楚2.1 JDK版本怎么選部署Servlet項目第一步是確認JDK版本。不同版本的Servlet規(guī)范、Tomcat版本對JDK的要求不一樣。我給的推薦原則是生產(chǎn)環(huán)境用穩(wěn)定版本新項目用LTS版本。當(dāng)前環(huán)境下JDK 8和JDK 11仍然大量存在JDK 17也已經(jīng)非常主流。如果這個項目要跑在別人的老服務(wù)器上先問清楚對方的Java版本再決定用哪個版本編譯。編譯版本如果高于服務(wù)器運行版本啟動或運行時會直接報UnsupportedClassVersionError這個錯誤信息里會帶上版本號看到它基本就能定位。我自己的習(xí)慣是新項目統(tǒng)一用JDK 17本地開發(fā)和生產(chǎn)環(huán)境保持一致。老項目維護則看對方服務(wù)器跑的是什么不輕易升級。2.2 Tomcat版本和Servlet版本怎么對應(yīng)Tomcat的版本號和Servlet/JSP規(guī)范版本有對應(yīng)關(guān)系。簡單記幾個常用的Tomcat版本對應(yīng)Servlet規(guī)范Servlet包名Tomcat 8.5Servlet 3.1javax.servletTomcat 9.xServlet 4.0javax.servletTomcat 10.0.xServlet 5.0jakarta.servletTomcat 10.1.xServlet 6.0jakarta.servlet這是我們最常遇到的一個坑。Tomcat 10之后包名從javax.servlet換成了jakarta.servlet。如果你還用javax.servlet的包名去寫代碼本地編譯能過因為本地引的是舊版servlet-api一部署到Tomcat 10上就報ClassNotFoundException。所以自己搭環(huán)境的時候建議先用Tomcat 9用javax.servlet包名網(wǎng)上大多數(shù)老教程的代碼都能直接跑。如果你用Tomcat 10就要注意引入的是jakarta.servlet-api代碼里的import也要改成jakarta開頭的包名。2.3 Tomcat目錄結(jié)構(gòu)要先看懂Tomcat解壓之后的主要目錄以Tomcat 9為例bin啟動和關(guān)閉腳本conf核心配置server.xml、web.xml都在這里libTomcat自身的庫servlet-api.jar就在里面logs日志輸出webapps應(yīng)用部署目錄war包放這里workJSP編譯后的臨時文件目錄webapps是部署最相關(guān)的目錄后面的實操主要就圍繞它。另外conf/server.xml里有連接器的配置端口就在這里改。默認是8080如果被占用了可以改但不建議輕易亂改因為改了之后別人的腳本、監(jiān)控、防火墻規(guī)則可能就全部對不上了。3. 從零寫一個Servlet并完成一次完整部署3.1 手工創(chuàng)建工程結(jié)構(gòu)這一步不需要任何IDE先用命令行把項目搭出來。這一步走通了你就能理解IDE背后幫你做的事。deploy-demo ├── src │ └── com │ └── example │ └── demo │ └── HelloServlet.java ├── web │ ├── WEB-INF │ │ └── web.xml │ └── index.html └── lib說明一下這個結(jié)構(gòu)的用意src存放Java源文件按包結(jié)構(gòu)組織。web是Web應(yīng)用的根目錄WEB-INF必須放在這里web.xml也必須在WEB-INF下。lib目錄是給項目自己的依賴jar包用的比如連接數(shù)據(jù)庫的驅(qū)動。WEB-INF這個目錄比較特殊它里面的內(nèi)容對瀏覽器不可見是給Tomcat用的。配置文件放這里外部用戶無法直接訪問安全性上有保障。很多人剛學(xué)的時候把Java文件直接丟在web目錄下Tomcat根本不會去編譯也不會執(zhí)行因為沒有class文件可加載。3.2 寫一個最簡單的Servlet我寫一個HelloServlet處理GET請求輸出一行HTML。package com.example.demo; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(h1Hello, Servlet deployed on Tomcat!/h1); } Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { doGet(req, resp); } }注意到doGet方法里我把響應(yīng)類型設(shè)置成了text/html并且指定了charsetUTF-8。這一步很多人會漏漏了的結(jié)果就是瀏覽器里中文全變成亂碼。后面問題排查部分還會再講。如果項目用的是Tomcat 10只需要把代碼里的javax全部替換成jakarta邏輯完全一樣。3.3 配置web.xml告訴Tomcat路由規(guī)則光有類還不行Tomcat不知道這個類對應(yīng)哪個URL必須在web.xml里聲明。web.xml是Servlet規(guī)范里約定的部署描述文件容器啟動時會解析它。?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 display-nameDeployDemo/display-name servlet servlet-namehello/servlet-name servlet-classcom.example.demo.HelloServlet/servlet-class load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namehello/servlet-name url-pattern/hello/url-pattern /servlet-mapping /web-app這里面有三個點要講清楚。第一servlet-name是邏輯名servlet-class才是全限定類名映射的時候通過邏輯名關(guān)聯(lián)。兩個name必須完全一致寫錯大小寫、多個空格都不行。第二url-pattern就是瀏覽器訪問的路徑。配了/hello之后通過http://localhost:8080/應(yīng)用名/hello就能訪問到這個Servlet。url-pattern的寫法要符合Servlet規(guī)范比如/開頭的路徑或者*.do這樣的擴展名映射不能隨便寫。第三load-on-startup表示是否在Tomcat啟動時就實例化這個Servlet。默認是第一次訪問時才實例化懶加載配了數(shù)字之后數(shù)字越小越先加載。生產(chǎn)環(huán)境里初始化比較重的Servlet建議配置這個屬性啟動時完成初始化避免第一個用戶訪問時等很久。3.4 編譯注意classpath要帶上servlet-api編譯類的操作很簡單但是classpath必須包含servlet-api.jar否則編譯報錯找不到HttpServlet。javac -encoding UTF-8 \ -classpath /path/to/tomcat/lib/servlet-api.jar \ -d web/WEB-INF/classes \ src/com/example/demo/HelloServlet.java-d參數(shù)指定class文件的輸出目錄。我直接輸出到了web/WEB-INF/classes這是Tomcat約定的一個“類搜索路徑”class文件放在這里Tomcat啟動時就能根據(jù)全限定名找到。為什么要加encoding參數(shù)Windows平臺的默認編碼可能是GBK源文件如果本身是UTF-8編譯時不指定-encoding中文字符串在運行時就可能出現(xiàn)亂碼甚至編譯報錯。這個參數(shù)平時不顯眼在跨平臺部署時能省掉很多麻煩。3.5 打包成war包編譯完成之后整個web目錄就是一個標準的Web應(yīng)用目錄結(jié)構(gòu)。要把它部署到Tomcat最標準的做法是打包成war包。war包本質(zhì)就是jar包格式只不過約定好了里面的內(nèi)容是一個Web應(yīng)用。在web目錄的上一級執(zhí)行jar cvf deploy-demo.war -C web .這條命令的意思是把web目錄下的所有內(nèi)容打包deploy-demo.war就生成了。注意-C先進入web目錄再打包確保war包內(nèi)的路徑是以根開始而不是帶一級“web”路徑。否則Tomcat解壓之后會多一層web目錄訪問路徑就變了。打出來的war包可以用jar tf deploy-demo.war確認里面結(jié)構(gòu)是否正確重點看WEB-INF/classes/com/example/demo/HelloServlet.class和WEB-INF/web.xml是否在正確位置。3.6 部署到Tomcat兩種方式方式一把war包直接拷貝到webapps目錄。cp deploy-demo.war /path/to/tomcat/webapps/ cd /path/to/tomcat/bin ./startup.sh # Windows下是 startup.batTomcat啟動時會自動掃描webapps下的war包把它解壓到同名的目錄deploy-demo。然后訪問http://localhost:8080/deploy-demo/hello就能看到瀏覽器輸出“Hello, Servlet deployed on Tomcat!”。方式二開發(fā)期直接把目錄拷過去。如果沒有打war包也可以把整個web目錄改名為應(yīng)用名后拷貝到webapps下同時保留WEB-INF結(jié)構(gòu)。cp -r web /path/to/tomcat/webapps/deploy-demo這種方式在開發(fā)階段非常方便。改完Java代碼重新編譯覆蓋class文件刷新瀏覽器就能看到效果不需要重啟Tomcat。我做日常調(diào)試時經(jīng)常用這個方法省時間。3.7 驗證三個關(guān)鍵點部署完了一定要驗證而且要按順序驗證。第一看Tomcat啟動日志有沒有報錯。日志在logs目錄下catalina.out記錄了啟動過程如果有異?；灸軓倪@里看到。特別是SEVERE級別的日志基本就是部署失敗的原因。第二確認war解壓成功?？磜ebapps下是否生成了deploy-demo目錄。如果war包損壞Tomcat會解壓失敗此時訪問必404。第三訪問URL是否正確。上下文路徑是war包文件名所以war包名叫deploy-demo.war訪問路徑就是/deploy-demo。如果你把它改成demo.war路徑就變成/demo/hello。改文件名會直接影響URL這個要特別注意。4. 部署背后的工作細節(jié)Tomcat怎么加載你的應(yīng)用4.1 應(yīng)用上下文Context是什么Tomcat把每個Web應(yīng)用稱為一個Context。webapps下一個war包啟動后對應(yīng)一個Contextcontext路徑默認就是war包名不含.war后綴。這個路徑?jīng)Q定了URL的第一段。如果想把應(yīng)用部署在根路徑訪問時直接http://localhost:8080/hello需要把war包改名為ROOT.war。這是Tomcat內(nèi)置的默認Web應(yīng)用約定。注意大小寫ROOT不能寫成root我見過幾次因為文件命名不規(guī)范導(dǎo)致部署無效頁面怎么都訪問不到。4.2 WAR包解壓機制Tomcat在啟動掃描到war包時會把它自動解壓到同名目錄。下次啟動時如果發(fā)現(xiàn)同名目錄已經(jīng)存在并且war包沒有更新就不會重新解壓。這個機制帶來一個很實用的技巧更新應(yīng)用時直接拷貝新的war包覆蓋但一定要記得先刪除舊的解壓目錄否則可能出現(xiàn)新代碼沒有生效的情況。這個“明明改了代碼、運行還是舊的”的情況我排查過很多次十有八九是解壓目錄沒有清干凈。work目錄下的臨時文件同理JSP修改后沒有重新編譯時也可以清一下work目錄。4.3 不部署war包的另一種方式Context描述文件如果你的應(yīng)用不想放在webapps下還可以在conf/Catalina/localhost下放一個context描述文件指向任意磁盤路徑。比如創(chuàng)建conf/Catalina/localhost/demo.xml內(nèi)容如下Context docBase/data/webapp/deploy-demo path/demo /這樣配置之后Tomcat會把/data/webapp/deploy-demo這個目錄加載為一個Context訪問路徑/demo就指向這個應(yīng)用。這個方式在生產(chǎn)環(huán)境里比較常用應(yīng)用放在磁盤指定位置日志、數(shù)據(jù)目錄也相對集中升級時不需要動Tomcat目錄。注意path屬性在較新的Tomcat版本中可能被忽略實際路徑以文件名為主。也就是說文件叫demo.xml上下文路徑就是/demo。這個細節(jié)很多人不知道配置了半天發(fā)現(xiàn)路徑不對其實就是文件命名問題。4.4 為什么訪問頁面卻看到404404這個狀態(tài)碼在Servlet部署場景里有兩個高頻原因。一是上下文路徑輸錯了。比如war包叫demo.war你訪問的時候?qū)懗闪薲eploy-demo。這個錯誤很常見尤其是部署了多個版本的歷史war包時。二是應(yīng)用根本沒有成功加載。Tomcat啟動時如果加載失敗應(yīng)用不會啟動訪問自然404。排查看日志是最快的路徑不要只盯著瀏覽器。Tomcat啟動時如果加載失敗日志里的異常堆棧會直接告訴你問題在哪比如web.xml解析失敗、類沒有找到。5. 常見問題與排查技巧實錄5.1 高頻問題速查表這一部分是我在幫別人排錯時遇到的高頻問題整理成一個速查表按現(xiàn)象、原因、處理辦法來組織。問題現(xiàn)象可能原因處理辦法訪問返回404上下文路徑寫錯核對war包名和URL路徑訪問返回404web.xml映射錯誤檢查servlet-mapping的url-pattern和servlet-name訪問返回500Servlet代碼拋異?？碿atalina.out日志堆棧ClassNotFoundExceptionTomcat版本與包名不匹配Tomcat 10用jakarta.servlet9用javax.servletUnsupportedClassVersionError編譯版本高于運行版本用與服務(wù)器JDK匹配的版本重新編譯頁面中文亂碼響應(yīng)未設(shè)置charset在response設(shè)置ContentType或統(tǒng)一配置編碼Filter端口被占用其他進程占用了8080換端口或停掉占用進程更新的代碼不生效舊解壓目錄未清理刪除webapps下解壓目錄后重啟依賴類找不到第三方j(luò)ar包沒有打進war把jar放到WEB-INF/lib目錄5.2 幾個重點問題的排查現(xiàn)場端口占用這個問題很常見。Linux下用lsof -i:8080查占用情況Windows下用netstat -ano | findstr 8080。定位到PID之后確認不是關(guān)鍵進程再處理。如果你只是本地測試也可以直接改conf/server.xml里的Connector端口改成8081重啟即可。但改了端口所有訪問路徑都要跟著改這點要記住。類找不到的問題最大的坑是Tomcat版本和Servlet包名不匹配。Tomcat 10把javax.servlet全面換成jakarta.servlet老代碼直接部署必掛。新項目建議一上來就用Tomcat 10用jakarta包名后面升級不會有這個問題。舊項目如果是跑在Tomcat 9上就保持javax不動。還有一個很多人會踩的坑把自己項目的lib目錄里放了servlet-api.jar再部署結(jié)果啟動報重復(fù)類定義錯誤。servlet-api.jar是容器提供的不要在應(yīng)用里帶否則會出現(xiàn)類沖突。Tomcat的類加載機制是“父委托”應(yīng)用目錄里的類會優(yōu)先被加載放一個舊版本進去反而會把容器自己的版本屏蔽掉導(dǎo)致各種莫名的NoSuchMethodError。編碼問題的重災(zāi)區(qū)是Windows環(huán)境。一個項目里源文件是UTF-8跳轉(zhuǎn)頁面是GBK響應(yīng)頭里又沒設(shè)置charset出來的中文必亂碼。建議大家統(tǒng)一用UTF-8源文件、配置文件、數(shù)據(jù)庫連接URL、響應(yīng)ContentType全部統(tǒng)一亂碼問題能減少九成。5.3 看日志的正確姿勢很多人部署失敗之后第一反應(yīng)是問我我就反問一句日志看了沒看日志是排查的第一步也是基本功。Tomcat日志主要在logs目錄下。catalina.out是主日志啟動過程、應(yīng)用加載、異常堆棧都在這里。localhost.log記錄Web應(yīng)用初始化相關(guān)信息部署失敗的關(guān)鍵信息經(jīng)常在這里。還有l(wèi)ocalhost_access_log開頭的文件記錄訪問日志排查請求有沒有到達Tomcat非常有用。當(dāng)你訪問頁面返回404先去看localhost_access_log確認請求到底有沒有進來。如果日志里根本沒有這個請求那問題可能出在端口、防火墻、上下文路徑。如果有請求但返回404再看是不是應(yīng)用沒加載?？慈罩静皇窍箍匆磿r間順序看從啟動的第一行看到最后一行重點關(guān)注第一次出現(xiàn)ERROR或SEVERE的位置那往往就是根因所在。6. 部署優(yōu)化與自動化建議6.1 用構(gòu)建工具替換手工打包手工流程走一遍是為了理解原理但真正上了項目還用命令行打包就太累了。建議用Maven或Gradle管理項目。Maven項目的pom.xml里打包插件配置好之后mvn clean package就能直接生成war包。war包名稱可以用finalName控制避免默認帶版本號導(dǎo)致上下文路徑變化。build finalNamedeploy-demo/finalName plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-war-plugin/artifactId version3.3.2/version /plugin /plugins /build這里有個非常實用的經(jīng)驗war包名一旦定下來就不要隨便改。每次構(gòu)建生成固定名字的war部署腳本和監(jiān)控腳本都依賴這個路徑。如果maven每次都生成帶版本號的包比如deploy-demo-1.0.0.war那么上下文路徑就會變成/deploy-demo-1.0.0訪問地址跟著變發(fā)布腳本也要跟著改很痛苦。6.2 自動化部署與健康檢查發(fā)布頻率高了之后人肉拷貝不是辦法可以寫一個簡單腳本。bash腳本的核心邏輯大概是這樣的備份舊war包拷貝新war包刪除舊解壓目錄啟動Tomcat然后循環(huán)探測健康檢查URL。#!/bin/bash APP_NAMEdeploy-demo TOMCAT_HOME/opt/tomcat WAR_FILEtarget/${APP_NAME}.war # 1. 停掉Tomcat ${TOMCAT_HOME}/bin/shutdown.sh # 2. 清理舊版本 rm -rf ${TOMCAT_HOME}/webapps/${APP_NAME}* cp ${WAR_FILE} ${TOMCAT_HOME}/webapps/ # 3. 啟動 ${TOMCAT_HOME}/bin/startup.sh # 4. 輪詢探測應(yīng)用是否啟動成功 for i in $(seq 1 30); do if curl -s http://localhost:8080/${APP_NAME}/hello | grep -q Hello; then echo Deploy success exit 0 fi sleep 2 done echo Deploy failed, check logs exit 1注意腳本里curl探測的是具體業(yè)務(wù)頁面而不是只看Tomcat端口通不通。因為Tomcat進程起來了不代表應(yīng)用加載成功。有時候應(yīng)用初始化失敗Tomcat照樣監(jiān)聽8080但訪問應(yīng)用頁面就是404。用業(yè)務(wù)URL做健康檢查可以避免這個假象。6.3 部署環(huán)境盡量保持一致Java Web項目在跨環(huán)境時最容易出問題的就是JDK版本、Tomcat版本、配置文件這三者。版本不一致很多詭異問題根本不會發(fā)生一旦發(fā)生就很難解釋。我建議本地開發(fā)、測試環(huán)境、生產(chǎn)環(huán)境統(tǒng)一用一個Tomcat版本至少是一個大版本。比如全部用Tomcat 9.0.x而不是這邊用8.5那邊用9.0。JDK也一樣不要本地17、服務(wù)器8這么混搭。配置文件這塊數(shù)據(jù)庫連接配置盡量通過環(huán)境變量或外部配置文件注入不要寫死在代碼里。這樣部署腳本只需要維護一套模板不同環(huán)境替換環(huán)境變量就行。還有最后一個經(jīng)驗部署之前確認一個干凈的Tomcat實例。試過很多次一個跑過多個項目的Tomcatconf目錄里改過的配置可能已經(jīng)被上一個項目玩壞了與其仔細排查不如直接解壓一個新Tomcat一次到位。結(jié)尾我個人在實際操作中的體會是Servlet部署不難難在理解Tomcat的工作方式。把webapps目錄、Context、WEB-INF、war解壓這幾個概念真正理解透遇到問題就有基本的排查思路。很多人卡在404上一下午就是因為不知道Tomcat有日志這回事也不知道上下文路徑和war包名的對應(yīng)關(guān)系。最后再分享一個小技巧如果你只是想快速驗證Tomcat環(huán)境干不干凈可以用Tomcat自帶的examples應(yīng)用。訪問一下http://localhost:8080/examples/能打開說明容器本身沒問題接下來再排查你自己的應(yīng)用配置。這個技巧幫我省掉過很多次無謂的懷疑。掌握了這里面的原理之后后面再學(xué)Spring Boot的內(nèi)嵌容器你會發(fā)現(xiàn)很多思想是相通的。內(nèi)嵌Tomcat無非是把容器搬進了應(yīng)用里但還是同一套Servlet規(guī)范的底層邏輯。所以說Servlet部署這個基本功值得認真過一遍。