在Mac上装Tomcat再跑通一个Java Web项目听起来不难可这些年我帮人排查下来真正一次顺利跑通的人并不多。卡点通常很集中JDK装好了但JAVA_HOME没指对Tomcat启动一闪而过项目在IDEA里怎么都部署不上去还有人反复问“JSP编译后的Java类到底在哪个目录”。这篇文章我就把整个链路重新走一遍——从JDK环境准备、Tomcat下载安装到按标准目录创建一个Java Web项目再到IDEA里把Tomcat配置成服务器并启动项目最后附上高频报错的排查方法。适合刚换到Mac上做Java开发的同学也适合Windows老手想在Mac上快速搭一套本地开发环境的人。1. 准备工作先把JDK和Homebrew这两张底牌打好1.1 先看看Mac里有没有Java环境很多人一上来就跑去官网下载Tomcat结果双击startup.sh发现起不来排错排了半天才发现是JDK压根没装。所以在任何安装动作之前先在终端里做一次“体检”。打开终端依次执行三条命令java -version javac -version /usr/libexec/java_home -V第一条看的是JREJava运行时环境在不在第二条看JDKJava开发工具包在不在第三条是macOS自带的一个工具它会把系统里所有已安装JDK的路径完整列出来。如果javac报command not found说明你就算能跑Java程序也编译不了代码而Tomcat启动时需要用JDK去加载JSP和Servlet的编译工作。这里有个容易踩的坑java -version正常不代表javac -version正常。有些Mac用户之前装过Oracle的JRE或者装过某个软件顺手带了一个运行时环境结果只有java没有javacTomcat在启动时会走得磕磕绊绊。判断标准很简单——/usr/libexec/java_home -V能列出1.8、11、17这类版本号才算真的齐了。如果三行命令都没有输出或者只有第一行有输出那就直接看下一节老实装一个完整JDK。1.2 安装JDK推荐用Homebrew别去官网一顿乱下Mac上装JDK的姿势很多官网dmg包下载、手动解压tar包、用SDKMAN管理我都试过。但对大多数开发者来说最省心的还是Homebrew原因很简单后续升级、卸载、切换版本都方便不用自己维护一堆散落的安装包。没装Homebrew的话先装Homebrew。官网给的是这么一行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这行命令我见过很多人卡住报错原因五花八门但最常见的就是网络问题。如果提示curl: (35) LibreSSL SSL_connect或者下载超时别死磕换个网络环境重试或者把Homebrew的下载源切到国内镜像源再执行效果立竿见影。装完后会提示你把/opt/homebrew/bin加进PATH照着提示做就行。然后装JDK。我建议用OpenJDK一个是License干净另一个是Homebrew的软件源里维护得最勤快brew install openjdk17装完之后有个细节很多人会忽略Homebrew安装的OpenJDK不会自动出现在macOS默认的JDK目录里。你需要把它手动软链过去或者直接设置JAVA_HOME来指路。我比较推荐设置JAVA_HOME的方式因为后面Tomcat、Maven、IDEA全都认这个环境变量。另外补充一句如果你的老项目必须用JDK 8用brew install --cask temurin8装Eclipse Temurin发行版也是合规、免费、更新及时的方案。JDK版本和Tomcat版本有对应关系提前列个表方便选型Tomcat版本最低Java版本典型的Servlet/JSP规范适合场景Tomcat 8.5Java 7Servlet 3.1 / JSP 2.3还在维护的遗留项目Tomcat 9.0Java 8Servlet 4.0 / JSP 2.3最稳的存量项目首选Tomcat 10.0Java 8Servlet 5.0Jakarta EE 9需要迁移到新命名空间的项目Tomcat 10.1Java 11Servlet 6.0Jakarta EE 10新项目、Spring Boot 3.x配套这里最需要注意的是从Tomcat 10开始Servlet API的包名从javax.*变成了jakarta.*老代码不能直接跑必须要改import。如果你用Spring BootSpring Boot 2.x默认兼容javaxSpring Boot 3.x才是jakarta这个对应关系千万要看清楚不然部署一堆NoClassDefFoundError。1.3 把JAVA_HOME配置写到.zshrc里从macOS Catalina开始系统默认shell改成了zsh所以环境变量要写进~/.zshrc而不是~/.bash_profile。我之前就见过有人改了.bash_profile然后一直source不生效最后发现当前shell是zsh白白折腾半天。具体操作touch ~/.zshrc open -e ~/.zshrc在打开的文件里加上下面几行我用的是JDK 17你按实际情况改版本号export JAVA_HOME$(/usr/libexec/java_home -v 17) export PATH$PATH:$JAVA_HOME/bin然后执行source ~/.zshrc echo $JAVA_HOME java -version如果echo $JAVA_HOME能打印出类似/Library/Java/JavaVirtualMachines/openjdk-17.jdk/Contents/Home的路径就说明配置成功了。这里用得着/usr/libexec/java_home这个命令的原因是它可以自动帮你定位到当前Mac上对应版本的JDK安装路径不用手写死路径以后换版本也只要改数字就行。注意Tomcat的startup.sh脚本启动时只认JAVA_HOME或JRE_HOME环境变量。如果你这一节没配好后面Tomcat启动一定会报“Neither the JAVA_HOME nor the JRE_HOME environment variable is defined”这是排第一的高频错误。2. Tomcat下载与安装版本、目录、启动验证2.1 Tomcat版本怎么选下载到底下哪个包去官网tomcat.apache.org找到Download页里面会列出各个大版本每个大版本下面有几个小版本。选择原则很简单如果你没有特殊理由直接选Currently maintained的稳定版本即可如果公司的老项目指定了版本就按项目要求来。下载页面里通常有两种包tar.gz和zip。Mac和Linux用户用tar.gzWindows用户用zipWindows下那个.exe安装包千万别碰它只是把Tomcat包装成了Windows服务真正开发调试时大家都用zip包直接解压。用命令下载或直接在浏览器下载都可以这里给个命令行的示例cd ~/Downloads curl -O https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.89/bin/apache-tomcat-9.0.89.tar.gz tar -zxvf apache-tomcat-9.0.89.tar.gz版本号以你下载到的实际版本为准不用纠结具体小版本。如果官网下载慢可以换国内镜像源后面排查篇我再统一说。解压完之后把整个目录挪到你习惯的开发目录我自己习惯放在~/dev/servers/下面mkdir -p ~/dev/servers mv apache-tomcat-9.0.89 ~/dev/servers/2.2 解压并熟悉Tomcat目录一个能正常工作的Tomcat目录结构是固定的熟悉它对后面的排错非常有帮助。我见过不少人只认识webapps其他目录一概不管等出了问题就抓瞎。apache-tomcat-9.0.89/ ├── bin/ # 启动、停止脚本startup.sh和shutdown.sh都在这 ├── conf/ # 核心配置server.xml、web.xml、tomcat-users.xml ├── lib/ # Tomcat自身依赖的jar包比如servlet-api.jar ├── logs/ # 运行日志catalina.out、localhost.YYYY-MM-DD.log ├── temp/ # 临时文件目录 ├── webapps/ # 部署Web应用的地方war包放这自动解压 └── work/ # JSP编译后的Java源码和class文件这里有两个目录必须印在脑子里。第一是webapps所有Web应用的war包或解压目录都扔这里Tomcat启动时会自动扫描并部署第二是work这个目录专门存放JSP被编译成Servlet之后生成的index_jsp.java和index_jsp.class文件排查JSP问题全靠它。conf/server.xml是Tomcat最核心的配置文件端口、Host、Context全在里面。打开后你会看到Connector port8080 protocolHTTP/1.1 .../这个8080就是默认HTTP端口以后改端口也是改这一行。把这个目录结构当作“地图”来看待后面所有问题你都不会觉得找不到北。2.3 启动、停止、验证安装启动前先确认bin目录下的脚本有执行权限很多Mac用户从压缩包里解压出来之后直接运行会提示Permission deniedcd ~/dev/servers/apache-tomcat-9.0.89 chmod x bin/*.sh bin/startup.sh正常启动时终端会打印出类似Tomcat started.的字样。紧接着用浏览器访问http://localhost:8080能看到那只标志性的Tomcat猫主页说明安装成功。验证也可以走命令行curl -I http://localhost:8080如果返回HTTP/1.1 200那肯定是活的。要注意的是Tomcat启动后终端会“卡住”吗并不会startup.sh是把Tomcat作为后台进程启动的终端马上会回到提示符。等你想停的时候执行bin/shutdown.sh如果启动时终端直接抛错误堆栈不要慌先看logs/catalina.out和logs/localhost.YYYY-MM-DD.logTomcat的日志已经写得很清楚了90%的启动失败都能在这里找到原因。3. 创建Java Web项目标准目录结构一次说清3.1 什么是Java Web项目的标准目录结构很多人学Java Web时第一步就是被别人带着在IDEA里咔咔点出一个项目目录结构稀里糊涂就出来了。但如果你不了解标准结构后面换IDE、手动部署、打war包都会出问题。按Maven规范的标准目录结构是这样demo-web/ ├── pom.xml ├── src │ ├── main │ │ ├── java/ # 源码Java文件 │ │ ├── resources/ # 配置文件 │ │ └── webapp/ # Web应用根目录 │ │ ├── WEB-INF/ # 服务器私有目录 │ │ │ ├── web.xml │ │ │ ├── classes/ # 编译后的class文件输出到deploy时会到这 │ │ │ └── lib/ # 项目自己的依赖jar包 │ │ └── index.jsp │ └── test/webapp目录是整个Web应用的“展台”你放到这个目录下的JSP、HTML、CSS、JS都可以被浏览器直接访问。真正特殊的是WEB-INF这个目录下的内容外部浏览器无法通过URL直接访问它专门用来放web.xml这个部署描述符、编译后的classes和依赖的lib。保证安全只是原因之一更重要的是服务器需要靠这个目录来加载应用的类。如果你之前接触的是老式Eclipse Dynamic Web Project它的目录里用的是WebContent作用和webapp完全一样只是命名不同。Maven生态崛起之后src/main/webapp成了事实标准IDEA、Jenkins、Docker镜像构建工具全都认这个路径。3.2 手写一个最简单的Servlet项目话不多说直接建一个最简Servlet项目。这里我用Maven结构先创建目录和pom.xml。project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIddemo-web/artifactId version1.0.0/version packagingwar/packaging properties maven.compiler.source8/maven.compiler.source maven.compiler.target8/maven.compiler.target /properties dependencies dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency /dependencies /project注意两个点。第一packaging必须写成war因为我们要部署到Tomcat的应用是Web应用打成war包才能被容器识别jar包只是Java库不能直接扔进webapps跑。第二Servlet API的scope是provided因为Tomcat的lib目录里已经自带servlet-api.jar了打包时如果把它打进去反而可能和容器自带的类冲突。然后写一个Servlet类package com.example.demo; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; WebServlet(/hello) public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { response.setContentType(text/html;charsetUTF-8); response.getWriter().write(h1Hello from Tomcat/h1); } }这里用了注解WebServlet(/hello)来做映射简单直观。如果你更喜欢传统XML配置就在src/main/webapp/WEB-INF/web.xml里写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 servlet servlet-namehello/servlet-name servlet-classcom.example.demo.HelloServlet/servlet-class /servlet servlet-mapping servlet-namehello/servlet-name url-pattern/hello/url-pattern /servlet-mapping /web-app最后在webapp目录下放一个index.jsp哪怕内容只有一行% page contentTypetext/html;charsetUTF-8 %h2Hello JSP/h2也可以。整个项目就是一个最标准的Servlet JSP组合。它能让你直观看到Java Web项目的生命周期浏览器请求URL、Tomcat根据映射找到Servlet、Servlet处理逻辑并返回HTML。3.3 打包、部署到Tomcat项目写好了用Maven打包mvn clean package构建成功后target目录下会生成demo-web.war。war包本质上就是一个zip压缩包里面包含了完整的webapp目录结构。把这个war包复制到Tomcat的webapps目录下cp target/demo-web.war ~/dev/servers/apache-tomcat-9.0.89/webapps/然后启动Tomcat访问curl http://localhost:8080/demo-web/hello浏览器访问也一样。为什么war包不用手动解压因为Tomcat在启动时会扫描webapps目录发现war包就自动解压成同名目录这个过程叫自动部署。如果你想让它以根路径/访问把war包改名为ROOT.war再部署即可。有一点要注意如果你在Tomcat运行期间直接覆盖war包有些版本会出现部署不同步的问题。稳妥的做法是先执行bin/shutdown.sh停止服务替换war包再启动。开发环境可以偷懒生产环境别这么干。4. 在IDEA里配置Tomcat并启动项目4.1 先跟IDEA说“我要用这个Tomcat”IDEA本身不内置Tomcat它只是把你本地的Tomcat“接管”过来帮忙调用启动脚本、读取端口、显示日志。所以第一步是先告诉IDEATomcat在哪。打开IDEA进入设置macOSIntelliJ IDEA→Preferences...打开后选Build, Execution, Deployment→Application Servers点击选Tomcat Server在Tomcat Home一栏选择你解压后的Tomcat目录例如/Users/你的用户名/dev/servers/apache-tomcat-9.0.89如果IDEA没有自动识别手动在JRE里选择JDK版本这一步配好之后后面创建运行配置时就能直接选用这个Tomcat实例。很多人下载完Tomcat就急着去Run Configuration里找找不到就懵了其实漏了这里。4.2 创建Java Web项目IDEA新建Java Web项目有两种常见路径。第一种用IDEA自带的Java Enterprise模板New Project→ 左侧选Java Enterprise新版本里可能叫Jakarta EE → 勾选Web Application→ 配置好Application Server为刚才添加的Tomcat。模板会帮你生成webapp/index.jsp和WEB-INF/web.xml对新手最友好。第二种如果你已经有一个普通Maven项目手动补全web目录。只需要在src/main下新建webapp目录然后在项目结构里把它标记为Web资源目录右键webapp→Mark Directory as→Resources Root。没有Web Application模板时这个操作就是让IDEA知道“这个目录是Web根目录”否则IDEA无法正确识别JSP和web.xml。我建议初学者用第一种方式省事、不容易漏配置。用老版本模板生成项目时web.xml的版本可能是2.3或3.1记得按你选的Servlet规范升级Tomcat 9配web.xml 4.0Tomcat 10配5.0不然会有怪异的兼容性问题。4.3 运行配置Artifact、Deployment、Application context项目建好后进入运行配置打开Run→Edit Configurations...点击选择Tomcat Server→LocalServer标签页里Application Server选择我们之前添加的TomcatHTTP port默认8080如果被占用可以改成8081On frame deactivation选择Update classes and resources这相当于热部署Deployment标签页里点击→Artifact选择项目名:war exploded爆炸war包也就是解压目录这里要重点解释一下war和war exploded的区别。war是打包后的压缩包每次改代码都要重新构建再部署流程长war exploded是“炸开”的war目录IDEA直接把编译后的class、资源文件同步到Tomcat加载的目录里改动刷新浏览器就生效。开发阶段选exploded能省下大量时间发布生产时才改成war。接着在Deployment里配置Application context。默认是空或/项目名_war_exploded建议改成一个简洁路径比如/demo这样访问地址就是http://localhost:8080/demo/。配好后点绿色的运行按钮IDEA会启动Tomcat并自动打开浏览器。如果你在控制台看到Connected to server又看到Tomcat的启动日志说明IDEA已经成功接管Tomcat了。此时访问你配置的context路径比如http://localhost:8080/demo/hello能看到Servlet输出整个链路就通了。4.4 JSP编译后的Java类在哪看JSP在运行时并不是被一行一行“解释执行”的而是有一个“翻译”过程用户第一次访问某个JSP时Tomcat会把它翻译成一个Servlet的Java源码再用javac编译成class文件之后执行的就是这个class。翻译产物就存放在Tomcat的work目录下。手工启动Tomcat的场景下路径一般长这样~/dev/servers/apache-tomcat-9.0.89/work/Catalina/localhost/demo-web/org/apache/jsp/index_jsp.java如果找不到用find命令直接搜find ~/dev/servers/apache-tomcat-9.0.89/work -name *index_jsp*有几个关键点用IDEA启动的Tomcat可能不会使用webapps目录下的部署目录IDEA会把你项目的exploded Artifact通过配置文件映射到Tomcat所以work目录的位置和手工部署时可能不同别拿手工部署的路径硬套。JSP文件修改后Tomcat会根据文件的最后修改时间判断是否重新翻译如果没改时间戳但内容变成旧版有可能是浏览器缓存了强制刷新或者重启Tomcat即可。看index_jsp.java能帮你在排查JSP里的500错误时确认EL表达式、JSTL标签到底被翻译成了什么Java代码对疑难杂症非常管用。5. 常见问题排查实录5.1 Tomcat启动闪退怎么办Tomcat启动闪退或者说是启动后浏览器立刻无法访问90%都是下面三种原因。第一种是JAVA_HOME没设好。执行bin/startup.sh终端直接抛Neither the JAVA_HOME nor the JRE_HOME environment variable is defined。解决方法就是回到1.3把JAVA_HOME写进~/.zshrc并执行source ~/.zshrc注意新开的终端才会生效。第二种是脚本没有执行权限执行chmod x bin/*.sh就能解决。第三种是启动过程中因为某个错误终止了。此时要看日志重点看logs/catalina.out和logs/localhost.YYYY-MM-DD.log。我遇到过一种情况Tomcat启动后马上被系统杀掉终端没有明显报错最后发现是端口被另一个进程占了Tomcat的Connector初始化失败。5.2 8080端口被占用找到占用者并解决端口占用是Java Web开发里的老朋友了尤其8080这个端口Spring Boot默认也是它。先查出占用者是谁lsof -i :8080输出里找到PID那一列然后kill -9 PID但我提醒一句在某些情况下端口是被系统服务或你安装的其它软件占用的kill -9可能杀掉不该杀的进程。Mac上AirPlay接收器这类系统功能偶尔会占端口如果不想动系统服务改Tomcat端口更稳。改法很简单打开conf/server.xml找到Connector port8080 protocolHTTP/1.1 ... /把8080改成8081重启Tomcat。改完之后IDEA的HTTP port也要同步改不然IDEA会按8080去找结果访问的还是别人。5.3 部署后404怎么排查项目能启动但访问页面就404这种问题很挫败。按顺序排查先确认Tomcat主页能打开访问http://localhost:8080。如果主页都打不开那就是服务压根没起来回到5.1排查。如果主页能打开但你的项目路径打不开检查这几项URL路径是否写对。Tomcat的应用路径默认和war包名或IDEA的Application context一致且大小写敏感。/DemoWeb和/demoweb是不同的路径。webapps下有没有对应目录或war包。手工部署的话war包被Tomcat自动解压后目录应该出现在webapps下面。Servlet映射是否配对。WebServlet(/hello)那URL就是/demo-web/hello多写一个后缀、少写一个前缀都会404。是不是访问了不该直接访问的资源。http://localhost:8080/项目名/WEB-INF/web.xml必然404这是Servlet规范强制规定的安全限制。404问题最有效的排错地点还是日志logs/localhost.YYYY-MM-DD.log会记录每个请求的映射情况看到日志里的条目你就知道Tomcat到底把你的请求匹配到了哪里。5.4 中文乱码和热部署不生效中文乱码问题集中在三处。第一是JSP页面内容乱码。在JSP第一行写全% page contentTypetext/html;charsetUTF-8 languagejava %同时保证HTML里的meta charsetUTF-8也声明了。文件编码本身也必须是UTF-8IDEA右下角能看当前文件编码不是UTF-8就手动切一下。第二是Servlet输出的中文乱码。response.setContentType(text/html;charsetUTF-8)这句一定要在getWriter()之前调用顺序反了可能无效。第三是IDEA控制台乱码。在Help→Edit Custom VM Options里加一行-Dfile.encodingUTF-8然后重启IDEA。热部署不生效的问题常见于两种情况。一是IDEA的On frame deactivation没有选Update classes and resources改完代码后IDEA根本没把新class同步过去。另一种是你改了方法签名、常量、配置类这种结构性变化IDEA的“热部署”并不是万能的类结构变了它没法热替换只能重启或重新Run。5.5 下载慢、镜像源和Eclipse用户的一点补充Tomcat和Maven的官方下载源在某些网络环境下确实慢。Tomcat可以从Apache的镜像站下载国内常见的镜像源都有同步速度提升明显。Maven依赖下载慢的话在~/.m2/settings.xml里配置阿里云或华为云的Maven仓库镜像能大幅提高打包体验。如果你用的是Eclipse而不是IDEA流程也类似Eclipse→Preferences→Server→Runtime Environments→Add→ 选对应Tomcat版本 → 指定Tomcat目录然后新建Dynamic Web ProjectTarget runtime选刚添加的Tomcat右键项目Run As→Run on Server就可以了。Eclipse的Server视图里还能直接看到Tomcat的启动状态、部署的模块列表排错比IDEA更直白。最后再多说一句实在的这套流程我前前后后帮人弄过很多次每次都觉得“不就这点事吗”但每次都会遇到新的小坑。如果你照着这篇操作还是卡住请先忍住瞎猜的冲动老老实实去Tomcat的logs目录翻日志绝大多数问题都已经由Tomcat自己告诉你了。看日志这个习惯比任何工具都管用。平时开发的时候我也建议你用war exploded部署把热部署开起来改完代码直接刷新浏览器效率提升真的不是一点半点。等到部署到云服务器或者测试环境时再严格用war包走完整构建发布流程。这样本地跑得爽线上稳定又不翻车。