1. 从“404”说起：一个资深后端工程师的日常排障
“请求的资源不可用”——这句话对任何一个和Tomcat打过交道的开发者来说，都再熟悉不过了。它像一个沉默的守门人，用冷冰冰的HTTP 404状态码，将你挡在应用的大门之外。表面上看，这只是服务器找不到你请求的路径，但背后隐藏的原因却可能千差万别：从部署时一个字母的大小写错误，到复杂的Spring MVC拦截器配置，甚至是国产化替代过程中的兼容性陷阱。今天，我们不谈那些泛泛而谈的“重启大法”或“检查路径”，而是深入Tomcat和其上层应用（如Spring Boot）的肌理，系统性地拆解这个“状态报告”背后的每一种可能，并给出精准的“手术刀式”解决方案。无论你是刚被404困扰的新手，还是在考虑将Tomcat替换为宝蓝德（BES）等国产中间件的架构师，这篇文章都将是你手边最实用的排错指南。
2. 核心问题定位：404错误的四层诊断模型
遇到404，盲目尝试是最低效的。我习惯用一个四层模型来快速定位问题，从外到内，层层递进，这能帮你节省大量时间。
2.1 第一层：网络与访问入口检查
这一层排查的是最基础、也最容易被忽略的问题，通常发生在项目刚部署或环境变更后。
首先，确认你的访问入口是否正确。很多新手会混淆几个关键URL：
- Tomcat服务器根地址：通常是
http://localhost:8080。访问这个地址，你应该能看到Tomcat的默认欢迎页（一只叼着橄榄枝的猫）。如果连这个都打不开，说明Tomcat服务本身没有成功启动，问题可能出在端口占用、环境变量或启动脚本上。 - 你的Web应用上下文路径（Context Path）：这是你的应用在Tomcat中的“挂载点”。如果你将项目打包成
myapp.war并直接丢到webapps目录下，Tomcat解压后，默认的上下文路径就是/myapp。此时，你的应用根地址应该是http://localhost:8080/myapp。在Spring Boot中，这个路径可以通过server.servlet.context-path=/myapp来配置。 - 目标资源的具体路径：在应用根地址之后，才是你在代码中定义的Controller路径或静态资源路径。例如，一个
@RequestMapping(“/hello”)的控制器，完整访问地址是http://localhost:8080/myapp/hello。
注意：在IDE（如IntelliJ IDEA）中运行项目时，务必要分清“Tomcat服务器配置”中的“部署路径(Deployment)”和“应用上下文(Context)”。IDEA有时会自动生成一个带版本号或特殊字符的上下文路径，这会导致你预期的访问地址失效。最佳实践是在IDEA的Tomcat运行配置中，将“Application context”明确设置为
/或你指定的路径。
其次，检查浏览器缓存和网络代理。这是一个经典的“坑”。你的代码已经更新，但浏览器顽固地显示旧页面的404。按Ctrl+F5进行强制刷新，或打开开发者工具（F12），在“网络(Network)”选项卡中勾选“禁用缓存(Disable cache)”。另外，某些网络环境或本地开发的代理设置（如Charles、Fiddler）可能会干扰请求，暂时关闭它们进行测试。
2.2 第二层：应用部署与结构验证
当入口无误后，我们需要确认应用是否被Tomcat正确识别和加载。核心检查点是Tomcat的webapps目录和日志文件。
进入Tomcat的webapps目录，找到你的应用文件夹（或WAR包）。对于一个标准的Web应用，其内部必须包含WEB-INF目录。WEB-INF下通常要有：
web.xml: 部署描述符文件。对于Servlet 3.0+（包括Spring Boot）的应用，这个文件可能不是必需的，但它的存在与否及内容正确性，在特定环境下至关重要。classes目录: 存放编译后的Java类文件。lib目录: 存放应用依赖的JAR包。
如果WEB-INF目录缺失、结构损坏，或者web.xml配置错误（例如，将Servlet映射到了错误的url-pattern），Tomcat就无法正确初始化你的应用，所有请求自然都会404。
最关键的证据在日志里。打开Tomcat的logs目录，重点查看catalina.out和localhost_yyyy-MM-dd.log文件。在应用启动时，你应该能看到类似下面的关键行：
信息 [main] org.apache.catalina.startup.HostConfig.deployDirectory 正在把web应用程序部署到目录 [myapp] ... 信息 [main] org.apache.catalina.core.StandardContext.startInternal 容器[Catalina].[localhost].[/myapp]启动成功如果应用部署失败，这里会有明确的错误堆栈信息。如果根本没看到你的应用名相关的部署日志，那说明WAR包未被识别或server.xml配置有误。
2.3 第三层：Servlet容器与请求映射分析
这一层深入到请求处理的内部流程。Tomcat作为一个Servlet容器，其核心工作是接收HTTP请求，并根据配置将其分发给对应的Servlet处理。
静态资源404：如果你的HTML、图片、CSS/JS文件访问不到，问题通常出在静态资源映射上。在传统的web.xml中，有一个名为default的Servlet专门处理静态资源。在Spring Boot中，静态资源默认放在classpath:/static/,/public/,/resources/,/META-INF/resources/目录下，可以通过spring.web.resources.static-locations自定义。常见的坑是：自定义了WebMvcConfigurer或拦截器（Interceptor）后，不小心拦截或屏蔽了对静态资源路径的请求。
动态请求404（Controller不生效）：这是Spring MVC项目中最常见的情况。原因可能包括：
- Controller未被扫描到：确保你的Controller类位于Spring Boot主应用类（带
@SpringBootApplication注解的类）的同包或子包下。如果不在，你需要使用@ComponentScan注解显式指定扫描路径。 - 注解使用错误：
@Controller必须和@RequestMapping或其衍生注解（@GetMapping,@PostMapping等）配合使用。一个只有@Controller而没有映射注解的类，不会响应任何请求。 - 请求方法不匹配：在浏览器地址栏直接输入URL，默认是
GET请求。如果你的Controller方法只映射了@PostMapping(“/submit”)，那么用GET访问自然会404。 - URL路径拼写错误：注意大小写、斜杠和路径参数。
/user/info和/user/Info在大多数服务器上是两个不同的路径。
2.4 第四层：框架特性与高级配置排查
对于一些复杂项目或特定技术选择，问题可能藏在更深的地方。
Spring Boot的“欢迎页”与“错误页”：Spring Boot默认对根路径“/”有特殊处理。如果你没有定义处理“/”的控制器，它会尝试寻找index.html作为欢迎页。如果连欢迎页都没有，你访问“/”可能会得到一个Whitelabel Error Page（其中包含错误信息），而不是404。但如果你访问的是“/api/xxx”，不符合上述规则，就会直接404。此外，自定义的ErrorController可能会影响404页面的表现形式，需要检查其实现逻辑。
拦截器（Interceptor）与过滤器（Filter）的误杀：这是高级bug的温床。你写了一个拦截器，本意是拦截/admin/**路径，但由于路径模式配置错误（如/**），导致所有请求都被拦截并中断，最终表现为404。务必在拦截器的preHandle方法中加入调试日志，确认请求是否通过了拦截链。
关于国产中间件替代的思考：最近“将Tomcat替换成国产中间件宝蓝德”是一个热门话题。如果你正在做此类迁移，并出现了404，排查思路需要扩展：
- 规范兼容性：宝蓝德（BES）等国产中间件通常宣称兼容Servlet/JSP规范，但实现细节上可能存在差异。重点检查
web.xml中是否使用了Tomcat特有的配置或标签。 - 部署方式：国产中间件的WAR包部署、上下文路径配置、日志查看方式可能与Tomcat不同，需要查阅其官方文档。
- Spring Boot内嵌容器：Spring Boot默认内嵌Tomcat。替换为宝蓝德通常意味着要排除Tomcat依赖，引入宝蓝德的Starter，并可能需要对一些自动配置进行调整。任何在替换过程中遗漏的依赖或配置，都可能导致应用上下文初始化失败，从而引发404。
3. 实战演练：系统性解决404问题的操作清单
光有理论不够，我们通过一个完整的实战流程，将上述四层模型付诸实践。
3.1 第一步：基础环境与部署检查
- 启动验证：启动Tomcat，访问
http://localhost:8080。若无欢迎页，检查端口是否被占用（netstat -ano | findstr :8080），或查看logs/catalina.out的启动错误。 - 部署确认：将你的WAR包（例如
demo.war）放入tomcat/webapps/。观察该目录下是否自动生成了demo文件夹。如果没有，可能是WAR包损坏或Tomcat的自动部署被禁用（检查conf/server.xml中Host标签的autoDeploy属性）。 - 结构验证：进入
tomcat/webapps/demo/，确认存在WEB-INF/目录及其子结构。 - 日志定位：重启Tomcat，立即尾随日志
tail -f logs/catalina.out。搜索你的应用名“demo”，确认看到“启动成功”字样。如果看到“启动失败”，根据堆栈错误（如ClassNotFoundException, NoSuchMethodError）解决依赖或版本冲突问题。
3.2 第二步：请求路径与映射分析
假设我们的应用上下文是/demo，有一个UserController。
- 构造测试URL：
- Controller:
@RestController @RequestMapping(“/api”) public class UserController { @GetMapping(“/user”) public String get() { return “ok”; } } - 正确的访问URL：
http://localhost:8080/demo/api/user
- Controller:
- 使用工具测试：不要只依赖浏览器。使用Postman或Curl进行测试，可以更清晰地看到请求和响应。
curl -v http://localhost:8080/demo/api/user-v参数会输出详细过程，你可以看到服务器返回的完整HTTP状态码和头部信息，确认确实是404。 - 开启Spring MVC调试日志：在
application.properties中添加：
重启应用后，再次访问。日志会打印出所有已注册的控制器映射，以及当前请求被匹配到了哪个映射（或为何没被匹配）。这是诊断Controller级别404的终极利器。logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG logging.level.org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping=DEBUG
3.3 第三步：深入框架内部机制
当基础路径和Controller映射都正确，但依然404时，需要怀疑“请求是否真的到达了DispatcherServlet”。
- 检查DispatcherServlet映射：在传统的基于
web.xml的Spring MVC中，DispatcherServlet通常被映射到/。但在Spring Boot中，这是自动配置的。然而，如果你有自定义的Servlet或Filter，并且它们的映射路径是/*，它们可能会“吃掉”所有请求，导致请求无法到达Spring的DispatcherServlet。检查所有自定义的Servlet和Filter的映射范围。 - 静态资源处理器：尝试访问一个确定存在的静态资源，比如
http://localhost:8080/demo/css/style.css。如果也404，说明静态资源路径配置有问题。在Spring Boot中，可以通过spring.mvc.static-path-pattern来修改匹配模式，通过spring.web.resources.static-locations来修改资源位置。 - Profile与条件化配置：检查你的Controller或配置类是否被
@Profile注解标记，而当前激活的Profile不匹配。或者，是否使用了@ConditionalOnProperty等条件注解，导致某些配置在特定环境下未生效。
4. 疑难杂症与进阶排查实录
在实际开发中，总会遇到一些不那么直观的404场景。这里记录几个让我印象深刻的案例。
4.1 案例一：IDEA热部署与上下文路径的“幽灵”
现象：在IntelliJ IDEA中使用Tomcat插件运行Spring MVC项目，代码修改后热部署，有时会出现404，重启Tomcat又好了。
排查：IDEA的热部署机制有时会改变应用的上下文路径。例如，它可能会将应用部署到一个带有时间戳或内部ID的路径下，如/demo_war_exploded2。而你的浏览器可能还缓存着旧的访问地址/demo。或者，IDEA的“Update resources”和“Update classes and resources”行为不同，可能导致资源文件未同步。
解决：
- 在IDEA的Tomcat运行配置中，进入“Deployment”选项卡，将你部署的Artifact的“Application context”固定为一个明确的值，比如
/。 - 热部署后，不要直接刷新旧标签页。关闭浏览器标签，从IDEA控制台点击提供的链接重新打开，或者手动拼接正确的URL。
- 考虑使用Spring Boot DevTools，它的热重启机制通常更可靠。
4.2 案例二：@RequestMapping的继承陷阱
现象：一个基类Controller定义了@RequestMapping(“/base”)，子类继承后添加了@RequestMapping(“/sub”)，期望路径是/base/sub，但访问却是404。
排查：在Spring MVC中，@RequestMapping注解在类上的映射路径是不会被继承的。子类上的注解会完全覆盖父类。因此，子类的最终路径就是/sub，而非/base/sub。
解决：
- 如果需要在子类中拼接父类的路径，需要在子类注解中显式写出完整路径：
@RequestMapping(“/base/sub”)。 - 或者，重构设计，避免使用继承的方式来组合路径，而是采用组合或AOP等其他方式。
4.3 案例三：过滤器（Filter）中的请求转发/重定向错误
现象：在一个过滤器中，对某些请求进行了request.getRequestDispatcher(“/some-page”).forward(request, response);操作，但最终浏览器显示404。
排查：过滤器中的转发路径是服务器端路径。这个路径是相对于当前Servlet上下文的。如果你在过滤器中转发的路径/some-page没有对应的Servlet或控制器来处理，那么请求链在转发后就会以404结束。更隐蔽的是，如果转发后触发了另一个过滤器或拦截器，它们可能会修改响应或中断请求。
解决：
- 在过滤器中打印转发前后的路径和状态，进行调试。
- 确保转发目标路径是一个有效的、能处理的端点。
- 仔细检查过滤器的
doFilter链调用：在转发或重定向之后，通常不应该再调用chain.doFilter(request, response)，否则会导致重复提交响应或产生不可预知的行为。
4.4 常见问题速查表
| 问题现象 | 可能原因 | 排查步骤 |
|---|---|---|
访问localhost:8080即404 | Tomcat未启动或端口占用；webapps/ROOT目录被删除 | 检查进程、端口；查看logs/catalina.out启动日志 |
| 应用上下文路径访问404 | WAR包未解压/损坏；WEB-INF缺失；应用启动失败 | 检查webapps下目录结构；查看localhost.log应用部署日志 |
| 静态资源（css, js, img）404 | 资源文件不在默认目录；静态资源路径被拦截 | 检查文件物理位置；检查WebMvcConfigurer和拦截器配置 |
| Controller接口404 | 注解错误；包未被扫描；请求方法不匹配 | 开启Spring MVC DEBUG日志；检查@ComponentScan；使用Postman测试不同方法 |
| 特定环境（如生产/测试）下404 | Profile特定配置未生效；环境变量差异 | 检查@Profile注解；对比不同环境的配置文件 |
| 迁移至新环境（如国产中间件）后404 | 规范兼容性问题；依赖缺失；配置方式不同 | 查阅新中间件官方文档；对比部署描述符；检查启动类依赖 |
5. 工具、习惯与预防措施
良好的开发习惯和工具使用，能从根本上减少404的出现。
- 日志是第一位：养成启动应用后第一时间查看日志的习惯。将日志级别调整为
DEBUG或TRACE能获得海量信息。 - 使用接口测试工具：Postman, Insomnia 或 Swagger UI。它们能帮你精确构造HTTP请求（方法、头、体），排除浏览器缓存和自动行为的影响。
- 单元测试与集成测试：为你的Controller编写Spring MVC Test单元测试。这不仅能验证映射是否正确，还能在代码变更后快速回归。
@SpringBootTest @AutoConfigureMockMvc class UserControllerTest { @Autowired private MockMvc mockMvc; @Test void shouldReturnOk() throws Exception { mockMvc.perform(get(“/api/user”)) .andExpect(status().isOk()) .andExpect(content().string(“ok”)); } } - 清晰的文档与约定：在团队内建立URL路径的命名规范，并使用Swagger或类似的API文档工具自动生成并维护接口文档。让前端和测试同学能随时获取到准确的接口地址。
- 理解“约定大于配置”：深入理解你所用框架（Spring Boot, Spring MVC）的默认约定。知道静态资源在哪、欢迎页如何工作、错误页如何映射，才能在自定义配置时做到心中有数，避免冲突。
解决Tomcat 404问题，本质上是一个“缩小搜索范围”的过程。从最外层的网络访问，到最内层的代码映射，每一步排查都基于上一步的验证结果。这个过程没有银弹，但有了这套系统性的方法和实战中积累的“坑点”地图，你就能从被动地搜索零散答案，转变为主动地、高效地定位问题根源。记住，服务器永远不会说谎，它给出的每一个404状态码，在日志里都留下了通往真相的线索。
