企业官网建设流程全解析

1. 传统SpringMVC项目在IDEA里启动为什么总出问题

如果你手上有一个用XML配置的老SpringMVC项目，之前一直在Eclipse或者MyEclipse里跑，现在换到IntelliJ IDEA，第一次点启动大概率是跑不起来的——要么404，要么ClassNotFoundException，要么Tomcat起来了但控制台一片红。这不是你的代码有问题，而是IDEA对项目的识别方式和Eclipse完全不同，加上SpringMVC这类传统Web项目依赖web.xml、WEB-INF目录结构、Artifact打包这几个环节，任何一环没对齐，application就起不来。

这篇内容我想聊的就是：怎么在IDEA里把一个传统SpringMVC项目配置到能正常通过Tomcat启动，包括工程导入、Artifact配置、Tomcat Server运行配置、web.xml加载顺序、常见启动报错排查这一整套流程。适合手上有遗留SpringMVC项目、需要在本机跑起来做维护或二次开发的同学，也适合刚接触IDEA、还不太清楚Artifact和Deployment之间关系的开发者。如果你已经在用SpringBoot，那这篇里的部分内容可以作为了解底层原理的参考，因为SpringBoot本质上也是把这些配置自动化了。

先明确一个前提：SpringMVC项目在IDEA里的启动，本质上是“把编译产物按照Web应用的标准目录结构打包成一个Artifact，再交给Tomcat容器去加载”。理解这句话，后面所有的配置都是围绕它展开的。很多人配不明白，是因为把IDEA当成了Eclipse——Eclipse里项目天然就是Web项目，右键Run on Server就行；IDEA里你需要显式告诉它：哪些目录是源码、哪些是资源、编译后的class放哪、WEB-INF里的jar怎么组织、上下文路径叫什么。这些信息IDE不会替你猜，尤其是从外部导入的工程。

另外要说清楚一点，这里讨论的“application启动”，指的是通过Tomcat容器把整个Web应用跑起来，而不是SpringBoot那种main方法直接启动。两者的启动入口、类加载顺序、上下文初始化时机都不一样，混着理解很容易绕进去。下面我按实际操作的顺序，从环境准备一路讲到报错排查。

2. 工程导入与运行环境准备的关键动作

2.1 JDK、Tomcat、Maven三者的版本对齐

老SpringMVC项目对版本是敏感的，尤其是JDK。很多2015年前后的项目跑在JDK 7或JDK 8上，Spring 4.x对JDK 9以上的模块化机制兼容性很差，你直接拿JDK 17去跑，大概率在类加载阶段就崩。所以第一步是确认项目原本的JDK版本，通常看pom.xml里的maven.compiler.source，或者看项目里有没有.classpath文件标注的JRE版本。

Tomcat的选择同样有讲究。SpringMVC项目一般用Tomcat 7、8、8.5这几个版本居多。Tomcat 9之后对Servlet API做了一些调整，老项目里的某些jar可能对javax.servlet包的依赖方式和Tomcat 10的jakarta.servlet不兼容。我个人的建议是：如果项目原本用的是Tomcat 8，就继续用8或8.5，别图新。可以在IDEA里配置多个Tomcat版本，不同项目用不同的。

Maven这边主要看仓库能不能拉到依赖。老项目经常依赖一些已经下架的私服jar，或者公司内网的snapshot。导入之后先执行一次mvn clean install -DskipTests，看依赖能不能全部解析。如果报某个jar找不到，优先确认是不是仓库地址配置在settings.xml里被覆盖了。这个问题在实际维护老项目时出现频率非常高，我踩过好几次，最后发现是IDEA自带的Maven用了默认的central仓库，没读你本地的settings.xml。

注意：IDEA默认可能使用Bundled Maven，路径在Settings > Build Tools > Maven里。老项目建议改成自己本地安装的Maven，并把User settings file指向你日常用的settings.xml，避免依赖拉取行为不一致。

版本对齐这件事，说到底是让“编译环境”和“运行环境”一致。IDEA里可以给每个项目单独设置Language Level和SDK，在File > Project Structure > Project里设定。别小看这一步，我见过太多“本地编译过、一启动就NoSuchMethodError”的案例，根源就是编译用的JDK和Tomcat运行时用的JDK不是同一个大版本。

2.2 从Eclipse工程导入IDEA时的三个关键识别点

Eclipse项目和IDEA项目的元数据文件格式不同，前者是.project和.classpath，后者是.idea目录和*.iml。导入的时候IDEA会尝试解析Eclipse的配置，但经常解析不全，尤其是源码目录（Source Root）和资源目录（Resources Root）的标记。

第一个识别点是src/main/java之外的自定义源码目录。有些老项目为了兼容Eclipse，会把Java源码放在src根目录下，而不是标准的Maven目录结构。导入后你要手动在Project Structure > Modules > Sources里把这些目录标记成Sources，否则IDEA不编译它们，启动时自然就报ClassNotFound。

第二个识别点是web目录的位置。传统SpringMVC项目的Web根目录可能叫WebContent、webapp、WebRoot，位置也未必在src/main下。这个目录必须被明确识别为Web Resource Directory，IDEA才知道WEB-INF和web.xml在哪。正确做法是在Project Structure > Facets里添加Web Facet，然后把Web Resource Directory指向你的实际目录，Deployment Descriptor指向web.xml。

第三个识别点是依赖jar的引用方式。Eclipse项目里依赖经常放在WebContent/WEB-INF/lib目录下，直接以物理jar存在，而不是走Maven。IDEA导入这种项目时，需要把这些jar加到模块依赖里，同时在Artifact配置里确保它们被放进WEB-INF/lib。这一步漏了，启动时就会报各种NoClassDefFoundError。

提示：导入完成后先别急着配Tomcat，先在Project Structure > Modules > Dependencies里过一遍，看看有没有红色的、标着“missing”的依赖。有就先解决，别带着问题往下走。

我个人习惯是导入后立刻做一次“全量体检”：SDK版本对不对、源码目录标记全不全、依赖有没有缺失、Web Facet有没有加上。这四件事做完，后面配置Tomcat会顺很多。很多同学跳过这步直接去配Server，结果启动报错，又回头查依赖，来回折腾。

3. Application启动配置的核心步骤拆解

3.1 Artifact配置：WEB-INF目录结构的组装逻辑

Artifact是IDEA里最容易让人懵的概念。简单说，它是“把项目编译产物按照一个特定目录结构组装起来的一份输出”。对Web项目来说，这个目录结构必须符合Servlet规范：根目录下有WEB-INF，WEB-INF下有classes、lib、web.xml。Tomcat加载的就是这个Artifact。

配置入口在File > Project Structure > Artifacts，点加号选Web Application: Exploded。这里有个选择：Exploded和Archive。Exploded是展开的目录形式，改代码后重新编译就能生效，调试方便；Archive是打成war包，适合部署。本地开发一律选Exploded，别选错。

创建之后要检查右侧的布局，标准结构应该是这样：

• WEB-INF/classes指向模块的编译输出目录（compiler output）
• WEB-INF/lib包含所有依赖jar
• 根目录包含web.xml所在的Web Resource Directory内容

我见过最常见的错误是WEB-INF/classes这一项缺失或者指错了地方。如果它没指向target/classes（Maven项目）或模块的output目录，Tomcat启动时WEB-INF下就没有class，Spring的ContextLoaderListener加载web.xml里配置的contextConfigLocation时就会找不到类，直接抛异常。

还有一点是Available Elements面板里的库要手动双击加到WEB-INF/lib下。IDEA不会自动帮你加，你只把模块依赖配好了，Artifact里不体现，打包出来就是缺jar。这一步是纯粹的“手工活”，但必须做。

3.2 Tomcat Server运行配置的细节

Artifact配好之后，去Run > Edit Configurations，点加号选Tomcat Server > Local。这里有几个关键项：

第一是Application server，指向你本地的Tomcat安装目录。IDEA会自动读取它的lib，用来做编译期依赖。第二是Deployment标签页，点加号把刚才配的Artifact加进去，然后设置Application context。这个context就是访问路径的前缀，比如设成/myapp，那你访问的URL就是http://localhost:8080/myapp/xxx。很多404问题的根源就是这里，要么context设成了/但代码里写死了别的路径，要么设成了项目名但浏览器访问时没带。

第三是Server标签页里的端口和JVM参数。端口默认8080，冲突了就改。JVM参数这块，老项目经常需要调大内存，因为Spring容器启动时加载的bean多，Metaspace容易爆。可以在VM options里加-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m这类参数。另外如果项目有编码问题，加上-Dfile.encoding=UTF-8。

第四是On 'Update' action，建议设成Update classes and resources。这样你改完Java代码，点一下更新按钮（或者Ctrl+F10），Tomcat会热更新class和JSP，不用重启。对调试效率提升非常大。不过要注意，改XML配置和Spring的bean定义时热更新不一定生效，该重启还是得重启。

3.3 web.xml与Spring容器的加载顺序

Tomcat启动一个Web应用的流程，简单说是：读取web.xml，按<listener>和<context-param>的顺序初始化，然后加载<servlet>。SpringMVC项目通常配两个东西：一个是ContextLoaderListener，负责加载Spring的根容器（service、dao这些）；一个是DispatcherServlet，负责加载SpringMVC的子容器（controller、视图解析器这些）。

这两者的加载顺序有讲究。ContextLoaderListener先启动，读contextConfigLocation里配的applicationContext.xml；然后DispatcherServlet启动，自己的contextConfigLocation指向spring-mvc.xml。子容器能访问父容器的bean，反过来不行。如果你把service的bean定义在了spring-mvc.xml里，controller里能注入，但ContextLoaderListener里的其他bean就找不到它——这是设计上的隔离，不是bug。

启动报错里有一类就是“父子容器加载顺序错乱导致bean找不到”。比如在applicationContext.xml里配了一个@Autowired的bean，但那个bean实际定义在spring-mvc.xml里，启动时根容器先初始化，找不到依赖就报错。排查这类问题，先看两个配置文件的bean扫描范围有没有重叠或遗漏。

web.xml里<context-param>和<listener>的先后也有关系。context-param必须写在listener之前，否则Listener读不到参数。这个规则IDE不会帮你检查，写反了启动才报错。我一开始就栽过这个坑，排查了半天才发现是标签顺序问题。

4. 三种启动方式的实操对比与选择

4.1 IDEA内置Tomcat部署（推荐用于日常开发）

这是最常用的方式，配置好Artifact和Server之后直接点绿色三角。它的好处是集成度高，控制台输出、热更新、断点调试都在IDE里完成，改代码见效快。

具体操作路径：Edit Configurations > + > Tomcat Server > Local > 配置Application server > Deployment里加Artifact > 设context path > 启动。启动后控制台会打印Tomcat的启动日志和Spring的初始化日志，从里面能看到容器有没有正常加载bean、有没有映射URL。

有一个细节要注意：IDEA内置Tomcat启动时，用的工作目录和“独立安装的Tomcat”不一样，它会在C:\Users\你的用户名\AppData\Local\JetBrains\...\tomcat\下生成一套临时目录，把Artifact复制过去运行。所以你改Artifact配置后，有时候需要重启才生效。另外，日志文件也会在这个临时目录里，排查启动问题时可以去那找完整日志。

4.2 打War包丢进外部Tomcat

这种方式适合需要验证“最终部署形态”或者需要跟生产环境保持一致的情况。在Maven项目里执行mvn clean package，生成的war丢进Tomcat的webapps目录，启动Tomcat的bin/startup脚本。

这种方式的坑在于：IDEA里编译通过不代表打包后的war能跑。尤其是依赖scope的问题——如果某个jar在pom里写的是provided，打包时不会被放进WEB-INF/lib，运行时就找不到。Tomcat本身提供的servlet-api、jsp-api用provided是对的，但如果你不小心把业务依赖也写成了provided，部署时就炸。

提示：打包后可以先解压war看一眼，确认WEB-INF/lib下的jar数量跟你预期一致，WEB-INF/classes下有class文件。这一步花不了两分钟，能避免很多“部署后报错、本地却正常”的困惑。

4.3 用Maven插件启动（tomcat7-maven-plugin）

如果项目pom里配了tomcat7-maven-plugin，可以直接用mvn tomcat7:run启动，不依赖IDEA的Tomcat配置，也不依赖本地安装的Tomcat。这种方式的好处是轻量、可脚本化，适合快速验证。

配置大概是这样：

<plugin> <groupId>org.apache.tomcat.maven</groupId> <artifactId>tomcat7-maven-plugin</artifactId> <version>2.2</version> <configuration> <port>8080</port> <path>/myapp</path> <uriEncoding>UTF-8</uriEncoding> </configuration> </plugin>

uriEncoding这个参数建议一定加上，否则URL里的中文参数会乱码，这是很多老项目在GET请求里传中文时踩的坑。path对应访问路径前缀，跟IDEA里配context path是一个意思。

需要注意的是，这个插件内置的Tomcat版本比较老，只到Tomcat 7，对Servlet 3.1以上的特性支持有限。如果你的项目用了较新的API，可能跑不起来。它更像是“快速冒烟测试”用的，正式开发调试我还是推荐IDEA内置Tomcat。

三种方式对比一下：

5. 启动报错排查实录与高频问题速查

5.1 启动即报ClassNotFoundException的排查路径

这类错误几乎都跟Artifact配置有关。按顺序查三处：

一看WEB-INF/classes有没有指向正确的编译输出目录。进Artifact配置看布局项，确认它是module 'xxx' compile output。如果Module的output目录本身是空的，说明源码没编译，先执行一次Build > Rebuild Project。

二看WEB-INF/lib里有没有你的依赖jar。在Available Elements里把需要的库双击加过去。注意某些jar可能是providedscope，IDEA不会默认加进去，你需要手动添加到Artifact，或者改pom里的scope。

三看web.xml里listener和context-param指向的类名有没有写错。尤其是包名重构过之后，web.xml里的全限定类名可能还是旧的。这种错误很隐蔽，因为IDE不会校验XML里的字符串。

我遇到过一次特别典型的情况：项目在Eclipse里跑得好好的，导入IDEA后启动报ClassNotFoundException: org.springframework.web.context.ContextLoaderListener，最后发现是Artifact里WEB-INF/lib下压根没有spring-web的jar，因为pom里spring-web的scope被写成provided了。改回默认scope，重新构建Artifact，问题解决。

5.2 404问题的四种成因与区分方法

404分两类：一类是Tomcat起来了，但访问的URL没映射到任何servlet；另一类是应用根本没部署成功。

区分方法很简单：看访问根路径。比如你的context是/myapp，访问http://localhost:8080/myapp，如果返回Tomcat的欢迎页或目录列表，说明应用部署了，是URL映射问题；如果返回404且控制台有部署失败的日志，那是部署问题。

部署成功但404的常见成因：

• DispatcherServlet的<url-pattern>配的是/还是*.do。配/表示拦截所有请求（静态资源除外需额外处理），配*.do表示只拦截.do结尾。访问路径跟这个必须匹配。
• Controller上的@RequestMapping路径和实际访问路径不一致，尤其是带了context path后容易多写或少写。
• 视图解析器的前后缀配置和实际JSP文件位置对不上。这种情况一般不是404而是500，但如果视图没找到，也可能报渲染错误。
• context path设成了/，但代码或页面里写死了项目名作为前缀。

排查404最快的方式是看启动日志里有没有Mapped "{[/xxx],methods=[GET]}"这样的映射记录。有，说明URL注册成功了，问题在访问路径写法；没有，说明Controller没被扫描到，检查<context:component-scan base-package>的范围。

5.3 中文乱码与编码相关的配置项

老项目里乱码是高发问题，根源通常在三个地方：Tomcat的URI编码、Spring的字符编码过滤器、页面的编码声明。

Tomcat 8之后默认URI编码是UTF-8，但有些老项目配的Tomcat是7或者更早，默认是ISO-8859-1，GET请求的中文就乱。解决办法是在server.xml的Connector上加URIEncoding="UTF-8"，或者在IDEA运行配置的VM options里加参数。

Spring这边，web.xml里通常会配一个CharacterEncodingFilter，设置encoding为UTF-8，并强制forceEncoding为true。如果这个filter没配或者位置不对（必须放在所有filter最前面），请求参数的中文就会乱。

页面层面，JSP顶部要有<%@ page contentType="text/html;charset=UTF-8" %>，HTML里要有<meta charset="UTF-8">。响应头里的Content-Type也要对。这三者有一个不对，都可能出现乱码。

注意：如果是POST请求乱码，多半是CharacterEncodingFilter的问题；如果是GET请求乱码，优先查Tomcat的URIEncoding。这两者的处理位置不同，别混着改。

5.4 常见问题速查表

6. 从SpringMVC平滑改造到SpringBoot的过渡思路

很多同学配SpringMVC的初衷，其实是想把老项目迁到SpringBoot上。这里说几个实操层面的过渡思路，不涉及具体代码改写。

第一，先别动源码，先在SpringMVC项目上把功能跑通、把依赖关系理清楚。你只有完全理解现有项目的Web配置（web.xml、spring-mvc.xml、applicationContext.xml的职责划分），改造时才知道哪些要搬到SpringBoot的application.yml里，哪些要写成@Configuration类。

第二，改造的顺序建议是：先加一个SpringBoot的启动类（带@SpringBootApplication），把原web.xml里ContextLoaderListener和DispatcherServlet对应的配置拆成WebMvcConfigurer实现和@Bean定义；然后把JSP或视图解析的配置搬过去；最后处理静态资源和拦截器。别一上来就删web.xml，让它和SpringBoot启动类共存一段时间，逐步迁移。

第三，注意SpringBoot默认内嵌Tomcat，端口、context path、编码这些都在配置文件里改，跟原来在IDEA里点Server配置的体验完全不同。比如原来在IDEA里设Application context，SpringBoot里对应的是server.servlet.context-path。原来VM参数调的JVM内存，SpringBoot里还是靠启动参数或脚本。

第四，老项目里依赖的第三方jar如果和SpringBoot的依赖有冲突，用<exclusions>排除或者用dependencyManagement锁版本。这一步往往是改造中最耗时的，需要反复用mvn dependency:tree对比。

我个人做过几个这种迁移，体会是：把SpringMVC配明白这件事本身，就是迁移的前置功课。你在IDEA里每解决一个启动报错，其实就是在理解SpringBoot帮你还原了什么配置。等你把Artifact、web.xml、父子容器这套东西理顺了，看SpringBoot的自动配置就不再是黑盒。

最后分享一个我在排查启动问题时的小习惯：每次启动失败，不要急着改代码，先把控制台日志从头到尾读一遍，找到第一个Caused by，那个才是根因。后面的一长串异常往往都是它引发的连锁反应。很多人倒着看，从最后一个异常开始改，改了半天才发现方向错了。这个方法帮我省下的时间，比任何配置技巧都多。