前几天群里有人问了个很基础但很要命的问题他把一个JSP文件放进了WEB-INF目录结果浏览器直接访问报404怎么都想不明白甚至在群里怀疑是不是Tomcat坏了。我当时看到这个问题其实挺感慨的——WEB-INF这个目录几乎每个Java Web开发都见过但很多人对它的理解就停留在放web.xml的地方至于它为什么会有访问限制、限制是在哪一层生效的、Tomcat部署项目时到底做了哪些事往往是一团浆糊。这篇不是官方文档的复读也不是那种全是术语的源码分析。我尽量用干活的人说话的方式把WEB-INF目录的作用、Tomcat的部署方式、以及请求从端口进来之后是怎么一步步找到你的Servlet的这几件事串起来讲清楚。适合刚接触Java Web的初学者认真读一遍也适合写了两三年代码但没系统梳理过这些概念的开发者查漏补缺。看完之后至少你能答上来为什么WEB-INF不能直接被访问、war包部署和目录部署有什么区别、Tomcat的request是怎么路由到具体应用的。1. 先说清楚WEB-INF这只保险箱里到底锁了些什么1.1 一个标准Web应用目录的明暗两面先看一个典型的标准Java Web应用也叫Web Application解压后的目录结构随便找一个部署过的war包打开就是这样mywebapp/ ├── index.jsp ├── static/ │ ├── css/ │ └── js/ ├── WEB-INF/ │ ├── web.xml │ ├── classes/ │ │ └── com/example/HelloServlet.class │ └── lib/ │ ├── mysql-connector-java.jar │ └── log4j.jar └── META-INF/ └── MANIFEST.MF你可以把整个Web应用想象成一栋房子index.jsp、static目录这些是客厅、门窗来访的客人浏览器可以直接进入、直接看到。而WEB-INF目录就是房子的保险箱或者储物间客人是没法自己打开进去的只有房子的主人服务器端的代码才有钥匙。关于WEB-INF这个名字INF就是Information信息的缩写。从Servlet规范的角度来说WEB-INF是一个特殊的私有目录它里面的所有资源都不属于Web应用对外公开的文档根目录docBase的一部分。也就是说凡是放在WEB-INF里的东西默认都是只允许服务器内部访问的。这里有个很重要的点WEB-INF这个目录名是严格约定好的不能改名而且大小写都必须是WEB-INF。你要是手滑写成了web-inf或者Web-INFServlet容器是不会认的部署的时候该目录不会获得任何特殊保护里面的文件也会被当成普通静态资源直接暴露出去。1.2 web.xml、classes、lib这三个保险箱成员的分工WEB-INF下面最核心的是三个东西它们的职责完全不同很多人容易搞混。第一是web.xml。这是Web应用的部署描述符在Servlet 3.0之前你想注册一个Servlet、配置Filter、设置监听器、声明欢迎页面全都得在这个文件里写。Servlet 3.0之后虽然可以用注解比如WebServlet来替代一部分配置但web.xml依然承担着很多注解搞不定的活比如指定session超时时间、配置MIME映射、声明安全约束、设置初始化参数等。Tomcat启动的时候会解析这个文件然后根据里面的声明去创建对应的对象。没有web.xml的Web应用在现代Servlet容器中也能跑起来但你在用的时候要清楚它的存在。第二是classes目录。这里放的是Java类编译后的.class文件目录结构必须和包名一一对应。比如你有一个类com.example.HelloServlet那它的class文件就应该是WEB-INF/classes/com/example/HelloServlet.class。这个目录是动态编译和类加载的关键后面讲ClassLoader的时候还会提到。第三是lib目录。这个里面放的是Web应用依赖的第三方jar包。需要注意lib下的jar包只对当前这个Web应用可见不会影响其他应用。这也是Web应用实现依赖隔离的基础——你有两个应用一个用Log4j 1.x一个用Log4j 2.x只要各自把jar放在自己的lib下它们就能和平共处互不干扰。除了这三样WEB-INF下面也可以放其他资源和配置文件比如WEB-INF/spring-config.xml、WEB-INF/ftl模板目录等。只要你愿意可以把任何不希望被用户直接访问的资源丢进去然后通过服务器端转发forward来读取。1.3 为什么浏览器直接访问WEB-INF会拿到404很多初学者会在这个地方卡住我把一个hello.jsp放在WEB-INF下面然后在浏览器输入http://localhost:8080/mywebapp/WEB-INF/hello.jsp结果Tomcat直接返回404为什么原因要从两层来看。第一层是Servlet规范层面的约定。WEB-INF和META-INF这两个目录下的资源不允许通过Web容器直接对外提供访问。这是一个强制约定所有符合规范的容器Tomcat、Jetty、Undertow等都必须遵守。第二层是Tomcat具体实现层面的拦截。Tomcat在解析Web应用的资源时会通过StandardRoot去定位资源。在Tomcat 8及以上版本中StandardRoot的validate()方法会对资源的路径做校验凡是以/WEB-INF/或者/META-INF/开头的路径都会被判定为无效资源直接返回不存在。也就是说DefaultServlet对浏览器发来的/WEB-INF/...请求压根找不到任何可返回的资源于是只能交回404。所以这个拦截不是靠某个Filter、也不是靠web.xml里的安全约束来实现的而是Tomcat在内核级别的资源访问层就已经把这个目录私有化了。这样的设计就是为了防止用户直接下载你的web.xml里面可能有敏感配置、classes目录下的class文件可能包含可被反编译的业务逻辑、或者lib下的jar包可能包含内部API。但注意有一个例外服务器端的forward是允许读取WEB-INF下资源的。这也正是很多MVC框架比如Spring MVC把视图页面放在WEB-INF/views下面的原因——控制器通过RequestDispatcher把请求转发给/WEB-INF/views/user/list.jsp这个转发是服务器内部行为容器会放行。而你直接通过浏览器发起请求走的是外部访问通道就会被拦下来。这套机制既保证了视图不能被用户跳过控制器直接看到又保证了控制器能正常渲染页面。2. 部署的几种姿势拷war包、丢目录、写配置文件2.1 最省事的war包拷贝部署war包本质上就是一个Zip压缩包里面装的是整个Web应用的内容只不过扩展名是.war。它的全称是Web Application Archive官方建议的部署方式就是直接把这个包丢到Tomcat的webapps目录下面然后启动Tomcat。Tomcat在启动过程中会扫描webapps目录看到xxx.war文件后会自动解压成xxx/目录然后以/xxx作为Context Path上下文路径来部署这个应用。比如上面那个mywebapp.war部署后通过http://localhost:8080/mywebapp/就能访问。这里有一个很多人不知道的细节war包自动解压是分版本的。Tomcat 8.5及之前的版本如果检测到war包比同名的解压目录新会重新解压覆盖如果war包和目录的日期相同则直接用现有目录。Tomcat 9之后默认行为有一些调整但总体逻辑还是尽量使用已有的解压目录除非war包更新。实际操作中我更喜欢用命令行的方式部署尤其是Linux服务器上。先把war包传到服务器然后执行cp mywebapp.war /opt/tomcat/webapps/启动Tomcat之后观察日志tail -f /opt/tomcat/logs/catalina.out只要看到类似Deploying web application archive和Deployment of web application archive has finished这样的日志就说明部署成功了。如果应用启动失败错误堆栈也会打在这个日志里。war包部署最大的好处是部署/回滚方便。换版本就替换war包删除应用就删掉war包和同名的解压目录整个过程不需要改任何配置文件。这也是我推荐生产环境使用的方式。2.2 exploded目录部署适合开发和改动频繁的场景exploded这个词翻译过来就是爆炸开的意思说白了就是不打包直接把整个Web应用的目录结构放到webapps下面。这种部署方式在开发阶段非常方便。你用IDEA跑项目的时候输出目录里往往就是exploded形式的目录结构。修改了一个JSP文件、一个静态资源文件刷新页面就能看到效果不用重新打包也不用重启Tomcat。mkdir -p /opt/tomcat/webapps/mywebapp cp -r build/* /opt/tomcat/webapps/mywebapp/Tomcat同样会把它当做一个Context部署路径名就是目录名。如果你不想用目录名作为访问路径可以在webapps下面建一个名字不同的目录然后在它的META-INF/context.xml里指定path不过这种方式用得少。exploded部署不适合生产环境最大的风险在于如果你在服务器上直接解压了war包然后只把新war包拷进去覆盖Tomcat可能不会乖乖地重新解压它会觉得已有解压目录是最新的。于是你看到旧文件还在新功能没生效以为部署失败了。这种war包和目录存在状态不一致的问题是我见过最常见的部署疑难杂症之一。2.3 通过配置文件把应用指向外部目录有时候你的应用并不想放在Tomcat的webapps目录下面而是放在服务器上的其他位置比如/data/apps/myapp。这时候你有两种选择。第一种是修改conf/server.xml在Host标签里加一个ContextHost namelocalhost appBasewebapps unpackWARstrue autoDeploytrue Context path/mywebapp docBase/data/apps/mywebapp reloadabletrue / /Hostpath是URL访问路径docBase是应用实际存放的磁盘路径。这样配置之后你访问http://localhost:8080/mywebapp/Tomcat就会去/data/apps/mywebapp这个目录下读取资源。但说实话我是建议你慎重直接改server.xml。因为每次Tomcat重启时会重新解析server.xml如果你手误改错了整个Tomcat都启动不起来。而且server.xml是Tomcat实例的全局配置文件改起来心理负担比较重。更推荐的做法是第二种在conf/Catalina/localhost目录下新建一个xxx.xml文件。这个目录是专门给每个Host虚拟主机存放Context配置的地方。文件名是什么应用路径就是什么。比如我建一个/opt/tomcat/conf/Catalina/localhost/mywebapp.xml内容如下Context docBase/data/apps/mywebapp reloadabletrue /那么访问路径就是/mywebapp不需要在文件里写path属性写了反而会被忽略或报错。这个方式最大的好处是改配置只影响单个应用不影响Tomcat其他部分。Tomcat支持热部署改这个xml文件后过一会儿它会自动重新加载应用不用重启Tomcat。2.4 三种部署方式的取舍对比我把三种方式放到一张表里方便你们对照着选型部署方式操作方式适用场景优点缺点war包拷贝拷贝war到webapps生产环境、版本发布打包标准化、回滚方便、部署简单需要解压过程首次启动稍慢exploded目录直接放解压目录到webapps开发环境、本地调试改静态资源即时生效、无需打包文件多传得慢、容易脏、不适合回滚Context配置文件在conf/Catalina/localhost下建xml应用放在外部磁盘、多应用共用Tomcat灵活指定docBase、不影响全局配置配置项稍微多、需要理解Context概念我个人心中的排位是生产环境主力用war包拷贝开发环境用exploded目录特殊场景比如应用必须放在特定磁盘路径用Context配置文件。别有哪种方式更高级的想法它们都是工具选最省事、最不容易出错的就行。3. 你请求的URL是怎么一步步找到WEB-INF的门卫的3.1 Tomcat内部的套娃式容器结构要理解一个HTTP请求是怎么在Tomcat内部流转的先得弄明白Tomcat的容器层级结构。它从外到内是这样的Server服务器 └── Service服务 ├── Connector连接器比如8080和8009 └── Engine引擎 └── Host虚拟主机比如localhost └── Context上下文对应一个Web应用 └── Wrapper包装器对应一个Servlet这个结构看起来抽象但其实对应关系非常简单。一台Tomcat实例就是一个Server一个Server下可以有多个Service每个Service至少有一个Connector和一个Engine。Connector负责监听端口把HTTP请求解析成内部对象Engine负责最终处理请求。Engine下面可以有多个Host每个Host就是一台虚拟主机通过域名区分比如你配置了www.example.com和admin.example.com两个HostTomcat会根据请求头里的Host字段把请求分发给对应的Host。Host下面就是Context也就是我们部署的Web应用每个应用对应一个Context。Context再往下就是Wrapper对应一个个Servlet实例。你可以这么理解Tomcat本身就是一个大楼Engine是总管家Host是楼层管家Context是某个房间Wrapper是房间里的员工。请求进来大门口保安先看你找谁再一层层帮你把请求传递过去。3.2 Mapper组件Tomcat的内线导航员因为Tomcat支持一个端口上部署多个应用那么一个请求进来之后Tomcat是怎么知道要路由到哪个应用的答案是通过Mapper组件它是Tomcat内部非常关键的导航员。假设我的Tomcat上部署了两个应用/app1和/app2。当浏览器发起请求GET http://localhost:8080/app1/user/list HTTP/1.1Tomcat处理的大致流程是这样Connector比如NioEndpoint监听到8080端口有请求进来解析HTTP报文把数据封装成Request对象。注意这时候还没到应用层。CoyoteAdapter把容器内部的Request从协议层对象转成容器层对象然后调用Engine的getPipeline().getFirst().invoke(...)。Engine拿到请求后会调用Mapper进行路由。Mapper会根据请求的Host头、Context路径、Servlet映射这三层来做匹配先匹配Hostlocalhost再匹配Context/app1最后匹配WrapperServlet映射规则/user/*找到对应的Context后请求被交给Context下的Filter链和对应的Servlet处理。换句话说Mapper是一个缓存了所有部署信息的注册表。Tomcat每次部署应用的时候都会在Mapper里注册一条路由记录。这就是为什么我们刚刚部署一个应用后立刻就能通过URL访问到它——因为部署事件触发了Mapper的更新。3.3 WEB-INF这扇门是在哪一步被拦下的前面说到Mapper会根据URL去找Context和Servlet那么顺着这条链路WEB-INF的访问限制是在哪一步生效的答案是在资源定位阶段生效的。当用户访问http://localhost:8080/mywebapp/WEB-INF/web.xml时请求最终会被交给Context处理然后由Servlet来处理。但对于这种静态资源请求负责处理的是DefaultServlet。DefaultServlet在处理请求时会调用resources对象也就是StandardRoot去查找对应的Web资源文件。StandardRoot.validate()会对路径进行合法性校验protected boolean validate(String path) { if (path.startsWith(/WEB-INF/) || path.startsWith(/META-INF/)) { return false; } // 其他合法性检查... }当路径以/WEB-INF/开头时校验直接失败DefaultServlet拿到一个null资源于是向客户端返回404。这就解释了为什么你就算给WEB-INF下的某个文件配置了Servlet映射直接访问依然会失败。因为Tomcat在资源定位这一层就杜绝了外部访问的可能性Servlet根本拿不到实际资源。但注意META-INF目录里的context.xml可以用来配置Context而META-INF/MANIFEST.MF等也是内部资源同样不允许外部访问。3.4 顺带把ClassLoader双亲委派说透WEB-INF下的classes和lib目录既然不允许外部访问那Tomcat是怎么加载它们的这就牵涉到类加载机制。Tomcat采用了优先自己加载的类加载策略也叫反过来打破双亲委派。什么意思呢Java默认的类加载机制是双亲委派一个类加载器收到类加载请求先不自己加载而是先委托给父加载器父加载器再往上抛只有父加载器搞不定的时候才由自己加载。这种设计主要是为了保证核心类库不被覆盖。但Tomcat对Web应用做了特殊处理。每个Web应用有一个独立的WebappClassLoader它的加载顺序是这样的先从WEB-INF/classes里找再去WEB-INF/lib的jar里找如果找不到才委托给父加载器Common ClassLoader为什么这么设计因为Tomcat要保证每个Web应用之间的类能够互相隔离。应用A和应用B都部署在同一个Tomcat上A用的Spring版本和B用的Spring版本可能完全不同。通过WebappClassLoader每个应用先加载自己WEB-INF下的类这样就不会出现一个Tomcat上只能用一个版本的Spring这种窘境。这个机制带来的一个常见坑是如果你把某个jar同时放在了Tomcat的lib目录和应用的WEB-INF/lib目录下应用的类加载器会优先使用WEB-INF/lib下的那份而不是Tomcatlib下的那份。这经常导致版本不一致的诡异问题。所以我的经验是Tomcat的lib目录里尽量只放所有应用共通的、且版本高度稳定的jar其他一律放到应用的WEB-INF/lib里。4. 我这些年踩过的部署坑4.1 war包和同目录并存导致改了没生效这个坑我印象太深了。有一次我在服务器上更新一个应用把新的mywebapp.war直接拷进了webapps目录然后重启Tomcat结果发现访问到的还是旧版本的页面。我一度怀疑是浏览器缓存清了缓存还是不对最后打开解压目录一看里面的class文件还是旧的。原因其实前面已经提到Tomcat不会无条件解压war包。如果你之前是用解压目录方式部署的现在把war包丢进去同名的目录和war包同时存在Tomcat会比较两者时间戳。由于解压目录里的文件没有被删除它的时间戳比新的war包还新或者Tomcat干脆认为目录已经存在就不处理了所以应用还是从旧目录里加载。解决方案很简单粗暴更新war包之前先把旧目录删掉然后把war包丢进去再启动Tomcat让Tomcat从头解压。rm -rf /opt/tomcat/webapps/mywebapp rm -f /opt/tomcat/webapps/mywebapp.war # 上传新war包 cp mywebapp.war /opt/tomcat/webapps/ /opt/tomcat/bin/startup.sh这个习惯虽然简单但能避免真的是产线上的灵异事件。4.2 改server.xml忘了重启Tomcat不认账很多人刚接触Context配置时会直接改conf/server.xml加Context标签。改完之后心想Tomcat不是支持热部署吗但访问新的Context路径发现404或者发现改的docBase没有生效。这里要澄清改server.xml本身不会触发热部署。Tomcat的热部署检测的是webapps目录下的war包和Context XML文件conf/Catalina/localhost下的xml。server.xml是Tomcat启动时读取的全局配置里面的内容在启动阶段就被加载了改完必须重启Tomcat才生效。所以如果你要动态添加Context正确的做法是在conf/Catalina/localhost下新建xml文件。这个目录下的xml文件Tomcat会实时监控新建或修改后会自动部署或重新部署应用不需要重启。如果只是改个参数但不想让应用重启可以顺便看一眼reloadable属性但那个属性主要影响WEB-INF/classes下class文件变化的检测是有性能代价的生产环境我一般不开启。4.3 端口、Context Path、应用内部路径404排查三连问404排查是最常见的操作性需求。遇到访问404我一般按这个顺序查第一步确认Tomcat启动了没有、端口是不是对的。用命令看看端口监听状态netstat -tlnp | grep 8080如果没有输出说明Tomcat没起来或者端口被改了。有时候Tomcat起不来是因为8080被其他进程占了日志里会有明确的Address already in use。第二步确认应用有没有成功部署。看日志tail -n 100 /opt/tomcat/logs/catalina.out如果看到SEVERE: Error deploying web application archive之类的错误那部署就没成功先在日志里排查异常。第三步确认URL里的Context Path对不对。war包叫mywebapp.war部署后Context Path一定是/mywebapp。如果你用Context XML文件部署Context Path是xml文件名。很多人栽在这儿以为应用直接部署在根路径下访问http://localhost:8080/index.jsp实际上应该是http://localhost:8080/mywebapp/index.jsp。第四步确认应用内部的Servlet路径对不对。比如你的Servlet映射是WebServlet(/hello)那么完整访问路径应该是/mywebapp/hello不是/hello。JSP和静态资源的相对路径也同理。这一套排查下来绝大多数404问题都能解决。剩下那些解决不了的就去看Tomcat日志里最新的异常堆栈别瞎猜。4.4 Tomcat工作目录work的隐藏作用很多人不重视work目录但它其实很有用。Tomcat把JSP翻译成Java源码、编译成class都在这个目录里。如果你改了一个JSP但刷新后页面还是旧的除了浏览器缓存还可能是因为work目录下的编译产物没有被正确清理。遇到这种情况停掉Tomcat把work目录清空再重启/opt/tomcat/bin/shutdown.sh rm -rf /opt/tomcat/work/* /opt/tomcat/bin/startup.sh这算是我每次部署之后有条件就顺手做一遍的习惯能省去很多追踪神秘旧页面的时间。最后再分享一个小技巧如果你在本地开发时频繁改动WEB-INF/classes下的class文件不用每次重启Tomcat。可以在Context配置里把reloadable设为trueTomcat检测到class文件变化会自动重新加载应用。但是这个特性会带来额外的文件监听开销生产环境不建议开启否则高并发下你会明显感觉到性能下降。开发机上用起来是真的很香搭配exploded目录部署改代码、切到浏览器刷新、看效果整个循环非常顺畅。这些事看起来都很基础但恰恰是基础决定了你能在这个领域走多远。把Web应用的目录结构、部署形态、容器路由机制搞明白之后以后碰到Context path不正确、类加载冲突、war包不更新这些问题你就不会两眼一抹黑。到这个程度Tomcat在你眼里就不再是一个能启动的软件而是一个结构清晰、行为可预测的确定性工具了。