1. 项目导入后404的典型场景拆解

1.1 为什么偏偏是“导入的项目”容易出问题

从外部拿到的项目压缩包，解压后往开发工具里一导，Tomcat一启动，浏览器敲地址回车，白底黑字的404直接糊脸上——这个场景我见过太多次了。有意思的是，同样一套代码，如果是从零新建的项目，反而很少出这毛病。问题就出在“导入”这个动作上：导入意味着项目带着别人机器上的配置、目录结构、依赖路径一起搬过来，而开发工具的工程元数据、服务器的部署描述、编译输出目录这三者之间一旦对不上号，容器就找不到你要访问的那个资源，404 自然就来了。

先把概念理清楚。404 的本质是“服务器收到了请求，但在它认知的部署上下文里找不到对应资源”。注意这句话里的关键词是“部署上下文”。很多人一看到 404 就去翻代码，查 Controller 映射、查 web.xml、查注解，方向就偏了。代码层面的路径错误确实会导致 404，但导入项目这个场景下，更高概率的元凶是部署根本没成功或者部署到了错误的上下文路径。容器里压根没有你这个应用，或者应用挂在/foo下你却访问/bar，返回的都是 404，跟你的业务代码一行关系都没有。

所以排查的第一步永远是分清两类 404：一类是“应用没部署上”，一类是“应用部署上了但资源路径不对”。这两类的排查路径完全不同，混在一起查只会浪费时间。我在实际处理这类问题时，习惯先看服务器启动日志里有没有应用的部署记录，再看访问的 URL 和实际上下文路径是否一致，这两步能筛掉八成的情况。

1.2 导入动作到底改动了什么

要理解问题根源，得先搞清楚“导入”这个操作在背后做了什么。一个完整的 Web 项目在开发工具里其实由好几层东西构成：源码目录、编译输出目录、工程配置文件（记录项目类型、依赖库、构建路径）、服务器运行时配置（记录部署了哪些应用、各自的上下文路径）。导入操作通常只完整搬运了源码和部分工程配置，而服务器运行时配置和编译输出目录的映射关系往往需要重新建立。

举个具体的例子。项目在原来那台机器上，编译输出目录可能配置成WebRoot/WEB-INF/classes或者src/main/webapp/WEB-INF/classes，导入到新环境后，开发工具按自己的默认规则重新推断，可能把输出目录指到了build/classes或者target/classes。结果就是：源码编译成功了，class 文件也生成了，但生成的位置和服务器部署时读取的位置不是同一个地方。服务器部署时去WEB-INF/classes下找类文件，发现是空的，应用初始化失败或者部署了个空壳，访问任何路径都是 404。

还有一种常见情况是工程性质识别错误。Web 项目在工程配置里有个关键标记，标明它是个动态 Web 项目、Web 根目录在哪。导入时如果这个标记丢了或者被识别成了普通 Java 项目，开发工具就不会把它当成 Web 应用来部署，服务器里自然也就没有这个应用。这种问题的隐蔽性在于：项目在 IDE 里看起来一切正常，代码能编译，就是访问不了。

1.3 排查前的三个基础确认

动手改配置之前，有三件事必须先确认清楚，否则后面全是瞎忙。

第一，确认 Tomcat 本身是活的。访问一下http://localhost:8080，能看到 Tomcat 的欢迎页或者管理页，说明服务器启动正常、端口没被占用。如果连这个都打不开，那问题在服务器层面，跟项目无关，先去解决端口冲突或者启动失败。

第二，确认应用真的部署上去了。看 Tomcat 启动日志，找类似Deployment of web application archive或者Deploying web application directory的记录，看里面列出的应用名和路径。日志里没有你的应用，说明部署环节就断了；有你的应用但路径跟你访问的不一样，那就是上下文路径的问题。

第三，确认访问的 URL 拼写。这个听起来很傻，但我确实遇到过把项目名大小写打错、把端口号记错、多打一个斜杠的情况。尤其是导入的项目，项目名可能带着原作者的命名习惯，跟你以为的名字不一样。花十秒钟核对一下 URL 和部署日志里的应用名，比后面折腾半小时配置划算得多。

2. 上下文路径与部署配置的深度解析

2.1 上下文路径是怎么决定的

上下文路径（Context Path）是 URL 里紧跟在端口后面的那一段，比如http://localhost:8080/myapp/index.jsp里的/myapp。这个路径不是随便定的，它由部署配置决定，而部署配置的来源有好几个，优先级从高到低大致是：项目里自带的部署描述文件、开发工具的服务器配置、项目名默认推断。

导入项目时最容易踩的坑就在这里。原项目可能在部署描述文件里写死了上下文路径，比如在META-INF下放了个配置文件声明路径为/shop，导入后你没注意到，还按项目名/myproject去访问，那必然是 404。反过来，原项目没写死路径，开发工具按项目名推断，但项目名在导入时被改成了带后缀或者带前缀的形式，实际部署路径跟你预期的不一致。

我处理这类问题的习惯是：永远以部署日志为准。日志里写的是什么路径，你就访问什么路径，别猜。如果日志里的路径不符合你的需求，再去改配置。改配置的位置通常在开发工具的服务器视图中，找到部署的应用，编辑它的部署配置，里面有一项叫“上下文根”或者“路径”的设置，改成你想要的即可。改完记得重新部署，光改配置不重新发布是不生效的。

2.2 部署方式的选择与影响

开发工具往 Tomcat 里部署应用，常见的有两种方式：一种是直接把编译输出目录映射过去，服务器运行时读取的是工作空间里的文件；另一种是打包成 war 包再部署。这两种方式对 404 问题的影响不一样。

目录映射方式的好处是改代码后热更新快，但坏处是它依赖开发工具对“Web 根目录”和“编译输出目录”的正确识别。导入项目时如果这两个目录识别错了，映射就指向了错误的位置，服务器读不到页面和类文件，404 就来了。war 包方式相对独立，打包过程会把 Web 根目录下的内容按标准结构组装，只要打包配置对，部署出来的结构就是对的，但它对打包配置的准确性要求更高。

我的建议是：排查阶段先用 war 包方式部署一次，排除目录映射的干扰。如果 war 包部署后能正常访问，说明代码和 Web 资源本身没问题，问题出在目录映射配置上，回头去修映射；如果 war 包部署后还是 404，那问题在打包配置或者 Web 根目录的识别上，继续往下查。这个二分法能快速缩小问题范围，比一上来就盯着某一种部署方式死磕高效得多。

2.3 Web 根目录识别的常见偏差

Web 根目录是存放页面、静态资源、WEB-INF配置的那个目录，服务器部署时以它为基准组装应用结构。不同项目结构下这个目录的位置不一样：老式项目可能是WebRoot，标准 Maven 结构是src/main/webapp，还有些项目直接用项目根目录。导入项目时，开发工具需要正确识别这个目录，识别错了，部署出来的应用结构就是残缺的。

识别偏差的典型表现是：部署日志显示应用部署成功，但访问首页 404，访问WEB-INF下的资源也 404，整个应用像是空的。这时候去检查项目的工程配置，找到“Web 项目设置”或者“部署程序集”这类配置项，看里面列出的源目录和目标路径对不对。正确的配置应该把 Web 根目录映射到部署结构的根/，把源码输出目录映射到/WEB-INF/classes，把依赖库映射到/WEB-INF/lib。这三条映射缺一条或者指错方向，都会导致部署出来的应用不完整。

这里有个细节值得注意：有些项目导入后，部署程序集里会多出一些莫名其妙的条目，比如把整个项目根目录映射到了/，或者把源码目录也映射了进去。这些多余条目会让部署结构变得混乱，该在WEB-INF下的东西跑到了外面，该在外面的东西被盖住了。遇到这种情况，把部署程序集里的条目清理成标准的三条映射，往往能直接解决问题。

3. 从零复现：一次完整的排查与修复实操

3.1 环境准备与问题复现

为了把排查过程讲透，我用一个模拟项目走一遍完整流程。环境是常见的开发组合：某开发工具（版本不限，配置逻辑大同小异）、Tomcat 8.5、JDK 8。模拟项目是一个简单的 Web 应用，包含一个首页和一个测试用的 Servlet，打包成压缩包后解压导入。

导入后直接启动 Tomcat，浏览器访问http://localhost:8080/simulatedemo/，返回 404。此时先做基础确认：访问http://localhost:8080能看到 Tomcat 欢迎页，说明服务器正常；翻启动日志，发现日志里只有 Tomcat 自身的启动记录，没有任何关于 simulatedemo 应用的部署记录。这就定性了：应用根本没部署上去，属于第一类 404。

这个结论很关键，它把排查范围从“代码路径问题”直接缩小到了“部署配置问题”。如果日志里有部署记录但访问还是 404，那才需要去查上下文路径和资源映射。所以再强调一遍：先看日志，先看日志，先看日志。

3.2 定位部署失败的具体原因

应用没部署上，原因可能有好几层。先检查项目是否被识别为 Web 项目：在项目属性里找项目 facet 或者项目性质相关的配置，看有没有动态 Web 模块的标记，以及版本是否与服务器匹配。模拟项目导入后，这个标记是缺失的，项目被当成了普通 Java 项目，这就是部署失败的根因之一。

补上 Web 模块标记后，还需要配置 Web 根目录。在同一个配置界面里，指定 Web 内容的根目录为项目里的实际目录（模拟项目用的是WebContent），并确认编译输出目录指向WebContent/WEB-INF/classes。这两步做完，项目在开发工具眼里才算是一个合格的 Web 应用。

接着检查部署程序集。打开部署程序集配置，标准配置应该是三条：Web 根目录映射到/，源码输出映射到/WEB-INF/classes，依赖库映射到/WEB-INF/lib。模拟项目导入后这里只有一条残缺的映射，补全三条后保存。

最后回到服务器视图，把项目添加到服务器下，启动。这次日志里出现了部署记录，访问http://localhost:8080/simulatedemo/正常返回首页。整个修复过程的核心就是三件事：补 Web 项目标记、指对 Web 根目录、补全部署程序集映射。

3.3 关键配置的参数说明

把上面涉及的配置项整理成表，方便对照检查。这些配置项在不同开发工具里的叫法略有差异，但逻辑是一致的。

这张表里的每一行，我都实际遇到过对应的错误案例。尤其是编译输出目录和部署程序集这两项，导入项目时出问题的概率最高，因为它们是“隐式配置”——不像源码目录那样显眼，出了问题也不容易第一时间想到。

3.4 验证修复结果的完整流程

配置改完后不能只看一眼首页就完事，要按完整流程验证。第一步，重启服务器，看日志里应用部署记录是否正常，有没有异常堆栈。第二步，访问首页，确认静态资源能加载。第三步，访问一个动态资源（比如测试 Servlet），确认类文件被正确加载、请求能被处理。第四步，检查WEB-INF/lib下的依赖是否齐全，如果有数据库驱动之类的依赖，触发一次相关功能确认依赖可用。

这四步走完，才算真正验证了修复有效。我见过只验证了首页就以为万事大吉，结果动态功能一用就报类找不到的情况——首页是静态的，不经过类加载，验证不了编译输出和依赖映射是否正确。所以动态资源的验证不能省。

4. 高频问题速查与避坑经验

4.1 问题速查表

把这类 404 问题的高频原因和对应处理整理成速查表，遇到问题时按表逐项核对，比漫无目的地翻配置快得多。

4.2 几个容易忽略的细节

第一个细节：清理服务器工作目录。开发工具部署应用时，会在服务器的工作目录下生成展开的应用结构。有时候配置改对了，但工作目录里残留着上一次部署的旧结构，新旧混在一起导致行为异常。遇到改了配置不生效的情况，先把服务器停掉，删掉工作目录下对应应用的展开目录，再启动，让服务器重新展开。这个操作相当于“清缓存”，能解决不少玄学问题。

第二个细节：项目名里的特殊字符。导入的项目如果项目名带空格、中文或者特殊符号，部署时的上下文路径可能被转义或者截断，导致访问路径和预期不符。这种情况要么改项目名，要么在部署配置里显式指定一个干净的上下文根。我倾向于后者，改项目名可能牵连其他配置，显式指定上下文根更稳妥。

第三个细节：端口占用导致的假象。有时候 404 不是应用的问题，而是你访问的端口上跑着另一个服务。比如 8080 被别的程序占了，Tomcat 启动失败或者换到了 8081，你还在访问 8080，返回的 404 来自那个占端口的程序。确认端口的方法很简单：看 Tomcat 启动日志里实际监听的端口号，以日志为准。

4.3 实操心得：建立自己的检查清单

处理多了这类问题，我养成了一个习惯：把排查步骤固化成清单，每次遇到 404 按清单走一遍，不凭记忆、不跳步。清单的顺序是：服务器是否正常、日志是否有部署记录、部署路径与访问 URL 是否一致、Web 根目录与输出目录映射是否正确、依赖是否齐全、是否重新部署。这个顺序是从外到内、从粗到细，每一步都能排除一批可能性，走到最后基本都能定位到根因。

清单的价值在于对抗“想当然”。人一旦有了先入为主的判断，比如认定是代码问题，就会跳过前面的基础检查直奔代码，结果在错误的方向上耗半天。按清单走，强制自己从最外层开始确认，反而最快。这个习惯不只适用于 404，其他部署类问题同样适用。

4.4 预防胜于排查：导入项目的规范动作

与其等出了问题再排查，不如在导入时就做对。我的规范动作是：导入后先不急着启动，先检查项目性质是否为 Web 项目、Web 根目录是否指对、编译输出目录是否在WEB-INF/classes下、部署程序集是否三条映射齐全。这四项检查花不了两分钟，但能避免后面大部分的 404。

另外，导入项目后第一次部署，建议用“清理后重新部署”的方式，而不是直接启动。清理动作会把旧的部署产物删掉，确保部署的是当前配置下的最新结构。这个习惯能规避掉“配置改了但部署的还是旧结构”这类问题。说到底，404 排查的核心不是记住多少种原因，而是建立一套从部署状态出发、逐层向内确认的排查逻辑，配置对了、部署对了，路径自然就对了。