搭一个本地Tomcat跑Java Web老项目这件事看起来已经是“上古操作”了但实际工作中我发现真到自己手动配一遍大多数人是会卡住的。好朋友最近在Mac上做毕业设计需要跑一个ServletJSP的老项目折腾了一晚上没跑起来最后跑过来问我。帮他弄完以后发现很多问题不是不会写代码而是对Tomcat的安装位置、项目结构、IDEA部署方式这些概念性环节不清楚。这篇就把整个流程一次性说透从零开始包含我踩过的所有坑。1. 为什么本地还要装一个Tomcat先想清楚你的使用场景很多人会问现在开发Java Web不都是Spring Boot内嵌Tomcat吗一个java -jar就完事了为什么还要单独装一个Tomcat、还要手动把项目war包丢进去这个问题问得没毛病但实际场景还真不少。1.1 哪种情况必须装独立Tomcat第一类是维护老项目。很多公司的系统还是SSH架构或者ServletJSP部署环境写死了Tomcat本地开发也必须用和线上一致的容器环境否则你在开发环境能跑一到生产环境就各种诡异问题。第二类是教学和毕业设计学校还在要求学JSP、Servlet、Filter这些基础技术这种项目天然就是打成war包丢进Tomcat跑的。第三类是你想真正理解Java Web运行原理搞清楚Servlet容器到底做了什么。我在帮朋友排查问题的时候发现最大的认知盲区在于大多数人根本不知道一个war包部署到Tomcat后发生了什么不知道web.xml怎么被解析不知道JSP第一次请求时会被编译成Servlet再执行。这些底层认知恰恰是调试问题的关键。1.2 不推荐全程用IDEA内置Tomcat方案的原因IDEA有内置的Tomcat集成可以一键启动但有个前提它本质上还是调用你本机安装的Tomcat只是帮你把部署路径和启动参数都配置好了。如果你完全依赖IDEA的“一键启动”一旦脱离IDE环境你连项目怎么跑起来都不知道。我在生产环境排障时遇到过不少同事本地能跑上服务器就懵了就是因为从不关心Tomcat目录结构、环境变量和启动脚本。所以这篇文章的思路是先手动装好Tomcat搞清楚它目录里每个文件夹的作用再用IDEA的集成功能去简化开发流程。两条路都走一遍你才能真正理解这套东西。2. 前置环境准备JDK版本、Homebrew和Tomcat下载方式的选择在Mac上装Tomcat之前第一件事是确认JDK装没装。Tomcat本身是纯Java写的没有JVM它什么都干不了。2.1 JDK版本选择和Tomcat的对应关系这里有一个极其容易踩的坑Tomcat版本和JDK版本必须匹配。Tomcat官方文档里有一张版本对应表核心逻辑如下Tomcat版本支持的最低JDK版本对应的Servlet规范命名空间Tomcat 8.5JDK 7Servlet 3.1javax.*Tomcat 9.0JDK 8Servlet 4.0javax.*Tomcat 10.0JDK 8Servlet 5.0jakarta.*Tomcat 10.1JDK 11Servlet 5.0jakarta.*Tomcat 11JDK 17Servlet 6.0jakarta.*这里面的关键变化在Tomcat 10Oracle把Java EE捐给了Eclipse基金会后命名空间从javax.servlet变成了jakarta.servlet。如果你的老项目用的是javax.servlet千万别图新装Tomcat 10否则项目里所有import全部报红Servlet、Filter、Listener全都找不到类。我给朋友推荐的组合是JDK 8 Tomcat 9兼容性最稳老项目几乎零改动直接跑。2.2 Mac上安装JDK的两种方式在Mac上装JDK第一种方式是去Oracle官网下载dmg安装包配置环境变量。第二种方式是用Homebrew安装命令是brew install openjdk8但Homebrew安装OpenJDK有一个坑安装完不会自动配置JAVA_HOME需要手动软链。Mac上的JDK路径在/Library/Java/JavaVirtualMachines/下Homebrew装的OpenJDK在/usr/local/opt/openjdk8/Intel芯片或/opt/homebrew/opt/openjdk8/Apple Silicon需要手动link到系统Java目录。我实际更推荐直接去Oracle或AdoptiumEclipse Temurin下载dmg安装包图形化安装装完在终端验证java -version echo $JAVA_HOME如果JAVA_HOME为空还需要在~/.zshrc里加一行export JAVA_HOME$(/usr/libexec/java_home -v 1.8) export PATH$JAVA_HOME/bin:$PATH然后执行source ~/.zshrc使其生效。注意Mac从Catalina开始默认shell是zsh要改.zshrc而不是.bash_profile。这个细节很多人搞混配了半天环境变量就是不生效就是这个原因。2.3 Tomcat下载Homebrew还是官网手动下载Tomcat的安装有两种方式。第一种是Homebrew安装brew install tomcat9第二种是官网手动下载。我的建议是开发用官网手动下载想体验标准部署流程也用官网手动下载。原因有三点Homebrew安装的Tomcat目录结构比较隐蔽通常在/usr/local/Cellar/tomcat9/9.x.x/libexec/下面新手容易找不到在哪里。Homebrew安装版不包含setclasspath.sh之类的脚本简化操作启动方式还是一样的但路径绕来绕去容易出错。手动下载的tar.gz解压后就是一个干净的Tomcat目录操作路径清晰以后排查问题也方便。手动下载我推荐去Tomcat官网找“Core”分类下的tar.gz版本例如apache-tomcat-9.0.98.tar.gz。下载完解压tar -zxvf apache-tomcat-9.0.98.tar.gz mv apache-tomcat-9.0.98 /usr/local/tomcat9把Tomcat移动到一个固定目录很重要后面配置IDEA、配置环境变量都要引用这个路径。直接放在/usr/local/tomcat9这种简洁路径比带版本号的路径好使升级时也方便切换软链。解压后先看一眼目录结构这是理解Tomcat的基础bin/ # 启动、关闭脚本 conf/ # 核心配置文件server.xml, web.xml, context.xml lib/ # Tomcat运行所需jar包 logs/ # 运行日志 webapps/ # 放置war包和web应用目录 work/ # JSP编译后的Java文件和class文件 temp/ # 临时文件2.4 验证Tomcat能否正常启动下载完成后先启动一次确认基础环境没问题。进入bin目录执行cd /usr/local/tomcat9/bin ./startup.sh启动成功后浏览器访问http://localhost:8080能看到那只猫的默认首页就说明基础环境OK了。如果页面打不开先看日志tail -f /usr/local/tomcat9/logs/catalina.out常见报错和处理方式我放到后文排查章节这里先不展开。3. 创建Java Web项目标准目录结构是一切的根基Tomcat能跑了接下来要创建一个能被Tomcat“听懂”的Java Web项目。这一步是大多数人翻车的地方因为很多人习惯了IDEA自动生成的目录结构不理解为什么必须是这个结构。3.1 标准目录结构到底长什么样一个标准的Java Web项目目录结构是这样的my-webapp/ ├── pom.xml # Maven配置文件如果是Maven项目 ├── src/ │ ├── main/ │ │ ├── java/ # Java源代码 │ │ │ └── com/example/ │ │ │ ├── servlet/ │ │ │ │ ├── HelloServlet.java │ │ │ │ └── UserServlet.java │ │ │ ├── service/ │ │ │ └── dao/ │ │ ├── resources/ # 资源文件配置文件 │ │ │ ├── jdbc.properties │ │ │ └── log4j.properties │ │ └── webapp/ # Web应用根目录 │ │ ├── WEB-INF/ │ │ │ ├── web.xml # Web应用描述符核心 │ │ │ ├── lib/ # 依赖的jar包 │ │ │ └── classes/ # 编译后的class文件 │ │ ├── index.jsp │ │ ├── css/ │ │ ├── js/ │ │ └── images/ └── target/ # Maven编译输出目录这套结构不是随便定的而是Servlet规范强制要求的。发布到Tomcat后Tomcat的webapps目录下会多出一个以项目名命名的目录其中的WEB-INF有特殊含义。WEB-INF下的内容对浏览器不可直接访问只有通过Servlet内部转发或者web.xml配置的映射才能访问这个机制是安全边界的设计。比如你把数据库配置文件放WEB-INF下浏览器就访问不到大大降低了信息泄露风险。3.2 Maven项目还是普通项目我的建议是不管项目多小都用Maven项目。理由很简单编译器、依赖管理、war包打包都省心。IDEA新建项目时选Maven Archetype的maven-archetype-webapp会自动生成标准webapp结构。在pom.xml里关键依赖是servlet-api和jsp-api但要注意scope必须设为provided。因为Tomcat本身就带这些jar包如果你打war包时把servlet-api也打进去启动时会因为类冲突报ClassNotFoundException或者NoSuchMethodError这个坑非常低级又非常常见。一个最小可运行项目的pom.xml核心内容project modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmy-webapp/artifactId version1.0.0/version packagingwar/packaging properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target /properties dependencies dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version4.0.1/version scopeprovided/scope /dependency dependency groupIdjavax.servlet.jsp/groupId artifactIdjavax.servlet.jsp-api/artifactId version2.3.3/version scopeprovided/scope /dependency /dependencies build finalNamemy-webapp/finalName plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.8.1/version configuration source1.8/source target1.8/target /configuration /plugin /plugins /build /project注意finalName它决定了打出的war包文件名。如果你希望部署后的访问路径是http://localhost:8080/my-webapp/这里就直接写my-webapp。3.3 手写一个最小的Servlet和web.xml为了测试整个链路通的随便写一个最小的Servlet即可。新建src/main/java/com/example/servlet/HelloServlet.javapackage com.example.servlet; import javax.servlet.ServletException; 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 req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(h1Hello Tomcat!/h1); } }然后编辑src/main/webapp/WEB-INF/web.xml?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-namemy-webapp/display-name welcome-file-list welcome-fileindex.jsp/welcome-file /welcome-file-list /web-app这里我用的是WebServlet注解方式注册比在web.xml里写servlet和servlet-mapping更简洁但两者的底层原理完全一样。如果是老项目用的纯web.xml方式只是写法不同映射逻辑都一样。再创建一个src/main/webapp/index.jsp% page contentTypetext/html;charsetUTF-8 languagejava % html head titleTomcat Test/title /head body h1项目跑通了/h1 a hrefhello访问HelloServlet/a /body /html3.4 用Maven打包成war包验证代码本身没问题在项目根目录执行mvn clean package如果构建成功target目录下会出现my-webapp.war。此时你可以手动把这个war包丢进Tomcat的webapps目录重启Tomcat然后访问http://localhost:8080/my-webapp/。这一条链路能跑通说明项目本身没问题后面再谈IDEA配置时心里就有底了。4. 在IntelliJ IDEA里配置Tomcat告别每次手动扔war包手动扔war包的方式适合验证但开发时效率太低。IDEA提供了一整套集成方案能把编译、部署、启动、享受日志输出合并成一次操作。但IDEA的配置界面选项比较多很多人照着教程配完还是启动不了下面拆开讲清楚。4.1 把项目导入IDEA并确认JDK与Maven配置打开IDEA选择Open选中刚才的Maven项目目录。第一次加载时IDEA右下角会提示“Maven projects need to be imported”等它导入完成。然后进入File-Project Structure确认三件事Project SDK选择1.8。Language level选择8。Modules下的Web模块存在且Deployment Descriptors和Web Resource Directories指向正确。如果你是手工创建的项目没有通过IDEA的Java Enterprise向导生成Modules下可能没有Web模块需要手动加选中模块右键Add-Web。这一步很多人漏掉导致后面配置Tomcat时找不到可用项目。4.2 添加Tomcat Server运行配置进入Run-Edit Configurations点击左上角加号选择Tomcat Server-Local。首次配置时要设置Tomcat的安装目录点击Configure旁边的按钮选中/usr/local/tomcat9目录。IDEA会自动识别版本号并完成基础校验。这里有个容易出错的地方如果你选择的是Tomcat Server - Remote那不是本地跑项目用的而是远程调试用的别选错了。配置界面里几个关键字段解释一下字段作用我的建议VM optionsJVM启动参数一般留空有内存需求才配置JRE启动Tomcat用的JRE确认指向1.8HTTP portTomcat监听端口默认8080被占用时改这里JMX portJMX监控端口默认1099On frame deactivationIDEA失焦时的动作选Update classes and resourcesOpen browser启动后自动打开浏览器建议勾选默认访问地址可改4.3 Deployment标签页是关键war还是war exploded很多教程到这里就完了但真正的重点藏在Deployment标签页。点击加号选Artifact会看到两个选项my-webapp:war和my-webapp:war exploded。这里必须解释清楚两者区别。war模式是把项目打包成war包再部署到Tomcat。它的特点是接近真实部署环境但每次改代码都要重新打包调试很慢。war exploded是解压后的目录形式IDEA会把target/my-webapp目录直接关联给Tomcat修改Java代码或JSP后配合“On frame deactivation”里的Update classes and resources可以实现热部署效率高非常多。日常开发选war exploded发布验证选war。这个选择没有对错但很多人选错后抱怨“IDEA改代码不生效”十有八九是用了war模式或者热部署配置没开。在Application context一栏默认是/my-webapp这表示访问路径是http://localhost:8080/my-webapp/。如果你想直接通过根路径访问也就是http://localhost:8080/这一栏就改成/。但生产部署时很少有人这么做建议保留项目名作为上下文路径避免混淆。4.4 完整的启动、停止和热部署操作配置完点击运行按钮IDEA会启动Tomcat并在Run窗口输出日志。启动成功后浏览器自动打开页面。开发中改代码后的热部署是有讲究的修改JSP文件直接刷新浏览器即可生效不需要重启。修改Java类IDEA失焦时如果配置了Update classes and resources会自动编译替换class文件但并不是所有情况下都可靠。静态方法、常量值等修改可能需要重启才能生效。修改web.xml、新增Servlet映射建议重启Tomcat因为web.xml在启动时解析热部署不检测这个文件。新增依赖jar包必须重启。4.5 补充一种方式直接把war包扔进webapps目录不在IDEA里跑Tomcat而是用IDEA的Maven工具先package出war包然后手动复制到/usr/local/tomcat9/webapps/目录下启动Tomcat。Tomcat检测到war包后会自动解压部署你也可以直接把解压后的目录删掉只保留war包Tomcat重启时会自动重新解压。这种方式是验证项目能否在“标准Tomcat环境”下运行的最可靠方法因为它绕开了IDEA的“特殊处理”。凡是遇到“IDEA里能跑换个环境就不行”的问题第一反应就是用这种方式复现一遍能快速定位到底是代码问题还是IDE配置问题。5. 启动后的那些坑端口冲突、乱码、JSP编译类不更新代码写了配置配了运行起来问题才是大头。下面是我和朋友实际踩过的典型问题每条都是我断断续续折腾过的这里一次性写清楚。5.1 端口8080被占用lsof和kill的实战用法Tomcat启动时报错Port 8080 was already in use.这个太常见了。Mac上排查端口占用用lsof命令lsof -i :8080看到占用进程的PID后确认不是重要服务直接killkill -9 PID但要注意Mac上有些进程是系统级服务比如ControlCenter、AirPlayReceiver等偶尔会占用某些端口。如果8080被这类系统服务占用建议直接改Tomcat端口而不是去kill系统进程。修改conf/server.xml里的这一行Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 /把port改成8081或者其他端口。改完后重启TomcatIDEA里的HTTP port也要同步改。5.2 启动成功但页面404war部署路径的真相有一种情况很迷惑Tomcat日志显示启动成功http://localhost:8080/能看到Tomcat首页但访问http://localhost:8080/my-webapp/就404。排查顺序如下第一确认war包是否真的部署到了webapps目录。Tomcat部署war包和直接放解压目录是有区别的如果你只放了解压目录而没有war包而且目录名和上下文路径不一致就会404。正确做法是看webapps下是否有对应的my-webapp目录且目录里有WEB-INF/web.xml。第二确认IDEA部署模式。如果你在Deployment里配置的Application context是/my-webapp2但项目pom.xml的finalName是my-webapp访问必须用配置的上下文路径。第三看日志。logs/localhost.yyyy-MM-dd.log会记录应用部署的详细异常。比如项目里的web.xml版本声明和Tomcat版本不兼容或者Servlet类初始化失败Throwable都能在这里找到。5.3 Tomcat日志里的中文乱码问题Mac上Tomcat日志中文乱码的原因通常是编码不一致。Tomcat默认使用UTF-8但控制台输出编码取决于终端环境和JVM的file.encoding参数。解决方案三步走第一步确保JSP和Servlet源码都是UTF-8编码JSP顶部加上% page contentTypetext/html;charsetUTF-8 pageEncodingUTF-8 %第二步修改conf/server.xml中的Connector加上URIEncoding参数Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 URIEncodingUTF-8 /第三步如果IDEA的Run控制台乱码在IDEA的Help-Edit Custom VM Options中加上-Dfile.encodingUTF-8重启IDEA。这三步做完绝大多数乱码问题能解决。如果还有问题可能是请求参数乱码检查Servlet里是否设置了request.setCharacterEncoding(UTF-8)以及数据库连接串是否带characterEncodingutf8。5.4 JSP编译后的Java类在哪看标题相关搜索词里有个很典型的问题“web项目配置tomcat后查看jsp编译后的java类”。这个需求通常是学习JSP原理或者调试JSP报错时要用到的。JSP的生命周期是第一次被请求时Tomcat把JSP翻译成Java源文件再编译成class文件最后执行_jspService方法。这些文件存放位置在Tomcat的work目录下。如果你用的是手动安装的Tomcat路径是/usr/local/tomcat9/work/Catalina/localhost/my-webapp/org/apache/jsp/在此目录下会看到类似结构index_jsp.java index_jsp.class hello_jsp.java hello_jsp.class用IDEA打开index_jsp.java可以看到JSP被翻译后的完整Java代码。如果你想调试JSP报错这个文件是最佳排查入口。比如JSP里写了一个不存在的变量编译报错信息会定位到这个Java类的某一行你反推回JSP原始行号就能找到问题。如果你用IDEA集成的Tomcat跑路径通常在/private/var/folders/...这样的临时目录下因为IDEA每次启动会复制一份独立的catalina.base。查找方法是IDEA启动日志里第一行会打印Using CATALINA_BASE: /Users/xxx/Library/Caches/...去这个目录下的work/Catalina/localhost/my-webapp/org/apache/jsp/就能找到。5.5 修改代码后浏览器不生效一度以为IDEA坏了这是一个经典的现象Java类改了页面刷新还是旧结果非要点重启才生效。原因基本是两个。第一个原因是热部署配置没生效。“On frame deactivation”要选Update classes and resources而且IDEA需要开启“Build project automatically”。在Settings-Build, Execution, Deployment-Compiler里勾选Build project automatically。两个条件都满足改Java类后切换到浏览器时才会自动编译更新。第二个原因是浏览器缓存。静态资源如CSS、JS文件浏览器会缓存刷新时不一定会重新请求。用开发者工具禁用缓存或者加版本号参数?v2解决。如果以上都试过还是不生效果断重启Tomcat。热部署机制本身有边界比如修改了web.xml、pom.xml、加了新jar包这些操作范围超出了热部署能力只有重启才可靠。不要在这些地方纠结浪费太多时间。5.6 启动时卡住或者执行很久才完成Mac上还有一种情况Tomcat启动时日志停在某个位置半天不动然后几分钟后才继续。这通常是JDK或者系统层面的随机数阻塞问题/dev/random在Mac上偶尔会阻塞。解决方法是在catalina.sh的JAVA_OPTS里加参数JAVA_OPTS-Djava.security.egdfile:/dev/urandom如果不想改脚本也可以在IDEA的VM options里加上这个参数。不过说实话这个问题在Mac上出现的概率不高我遇到一次加了参数后确实好了算是一个冷门但值得记录的坑。5.7 生产环境的Tomcat安全提醒不要用默认管理账号虽然不是Mac特有的问题但作为Tomcat体系的一部分必须提一下。很多人在本地启动Tomcat后顺手给conf/tomcat-users.xml配置了manager-gui角色用于访问管理后台。这在本地没问题但如果把这个配置原封不动带到生产环境等于把服务器管理端口暴露给公网。这些目录泄漏和默认口令风险是Tomcat被入侵的主要渠道之一。生产环境的建议是不开启manager和host-manager应用。必须开启时强制强密码并限制来源IP。所有应用上下文路径不要带版本号避免暴露版本信息。及时升级Tomcat版本关注安全公告里的CVE列表。6. 部署一次之后你会建立起的几个核心认识走到这一步你已经完成了从环境安装、项目创建、IDE集成到问题排查的完整闭环。这个过程虽然烦琐但它建立的认识是有长期价值的。第一你真正理解了“web容器”这个东西不是黑盒。Tomcat做的事其实就三件监听端口接收HTTP请求根据web.xml或注解找到对应的Servlet执行Servlet并返回响应。JSP的本质是Servlet的“糖衣”第一次请求时被翻译成Java类再执行这就是为什么JSP第一次访问慢、后面就快的原因。第二你搞清了IDE的集成和真实部署环境的边界。IDEA帮你自动处理了部署路径、classpath和重启流程但这些操作的底层逻辑在CATALINA_BASE、webapps、work这些目录里都能找到对应。以后遇到“IDEA能跑服务器不能跑”的情况你就知道检查什么了。第三你自己动手配置一遍之后再看Spring Boot内置Tomcat会透彻很多。Spring Boot那一套只是用spring-boot-starter-web依赖帮你把Tomcat内嵌进应用本质还是Servlet容器在跑只是不需要手动部署war包而已。理解了外部Tomcat的机制再去看内嵌Tomcat的配置和调优就会觉得清晰。最后分享一个小技巧以后新建环境时先下载并手动启动一次Tomcat确认端口通、首页能访问再去折腾IDE集成。Bin里的catalina.sh run命令可以前台启动并实时输出日志方便调试。遇到诡异问题先看logs/catalina.out里面的前10行往往就是根因。这套排查顺序能解决80%以上的“Tomcat莫名其妙启动不了”问题。