Spring MVC 作为 Java Web 开发中经典的 MVC 框架，至今仍在大量企业项目中使用。对于新手来说，跑通第一个 Hello World 往往是建立信心的关键一步。但很多人卡在配置、注解扫描或视图解析上，导致迟迟无法看到页面输出。本文会从零开始，使用 Maven 和传统 XML 配置的方式创建一个最小化的 Spring MVC 项目，并详细解释每一步的作用，最后集中梳理常见问题和注意事项。
环境准备与项目搭建
开始之前，需要准备好 JDK 8 及以上版本、Maven 3.6+ 以及一个趁手的 IDE（如 IntelliJ IDEA 或 Eclipse）。如果你习惯使用 Gradle，依赖管理部分稍作调整即可。本文以 Maven 为例，创建一个名为 spring-mvc-hello 的 Web 项目。
在 pom.xml 中引入 Spring MVC 和 Servlet API 依赖。注意 Servlet API 通常由容器提供，因此使用 provided 作用域。另外需要加入 JSTL 依赖以便在 JSP 中使用标签，同时配置 maven-war-plugin 让项目打包为 war 包。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>spring-mvc-hello</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>war</packaging>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<spring.version>5.3.30</spring.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${spring.version}</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>1.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.3.2</version>
</plugin>
</plugins>
</build>
</project>
接着配置 web.xml。传统 Spring MVC 项目的入口是 DispatcherServlet，它负责接收所有请求并分发给对应的控制器。在 web.xml 中声明 DispatcherServlet，并指定 Spring 配置文件的位置。同时设置 load-on-startup 为 1，让容器启动时立即加载 Spring 上下文。
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
version="4.0">
<servlet>
<servlet-name>dispatcher</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/dispatcher-servlet.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>dispatcher</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
</web-app>
最后创建 Spring 配置文件 dispatcher-servlet.xml，开启注解扫描并配置视图解析器。这里使用 <context:component-scan> 扫描控制器所在的包，使用 InternalResourceViewResolver 将逻辑视图名解析为 JSP 物理路径。
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc.xsd">
<context:component-scan base-package="com.example.controller"/>
<mvc:annotation-driven/>
<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="prefix" value="/WEB-INF/views/"/>
<property name="suffix" value=".jsp"/>
</bean>
</beans>
编写控制器与视图并运行
在 com.example.controller 包下创建 HelloController 类，使用 @Controller 注解标记为控制器，使用 @RequestMapping 映射请求路径。方法返回一个逻辑视图名，例如 "hello"，视图解析器会将其解析为 /WEB-INF/views/hello.jsp。
package com.example.controller;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
@Controller
public class HelloController {
@RequestMapping("/hello")
public String sayHello(Model model) {
model.addAttribute("message", "Hello, Spring MVC!");
return "hello";
}
}
在 /WEB-INF/views/ 目录下创建 hello.jsp，使用 EL 表达式获取控制器传递的数据。这个页面就是用户最终看到的输出。
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
<title>Hello Spring MVC</title>
</head>
<body>
<h1>${message}</h1>
</body>
</html>
将项目部署到 Tomcat（版本 8.5 或 9 均可），启动后访问 http://localhost:8080/spring-mvc-hello/hello，如果一切正常，浏览器会显示 "Hello, Spring MVC!"。整个请求处理流程可以简单概括为：客户端请求到达 DispatcherServlet，它根据 URL 找到对应的 Handler（控制器方法），执行方法并将模型数据传递给视图，最后渲染响应。
在实际开发中，你可能会使用 Spring Boot 来简化配置，但理解传统配置有助于深入掌握框架原理。Spring Boot 通过自动配置和嵌入式容器隐藏了大量细节，而手动搭建的过程能让你看清 DispatcherServlet、视图解析器和组件扫描各自扮演的角色。
常见问题与注意事项
很多初学者在运行第一个 Spring MVC 项目时会遇到各种 404 或者页面无法渲染的问题。这里集中梳理几个高频踩坑点，并给出解决方案。
404 错误：找不到对应的处理器
最常见的 404 原因是 <context:component-scan> 配置的包路径不正确，导致控制器未被 Spring 管理。请检查 base-package 是否包含了控制器所在的包。另一个原因是请求 URL 拼写错误，例如控制器映射为 "/hello"，但访问的是 "/helloworld"。此外，web.xml 中 DispatcherServlet 的 url-pattern 配置为 "/" 时，静态资源也会被拦截，如果控制器未正确处理静态资源，可能导致页面样式丢失或 404，此时可以添加 <mvc:resources> 配置来放行静态资源。
视图解析失败或 JSP 无法渲染
如果控制器返回的逻辑视图名与 JSP 文件位置不匹配，例如返回 "hello" 但 JSP 文件实际位于 /WEB-INF/views/hello.jsp，请检查视图解析器的 prefix 和 suffix 配置是否正确。注意 prefix 路径末尾是否有斜杠，suffix 是否包含点号。另外，如果 JSP 页面中使用了 EL 表达式但没有输出，需要确认 web.xml 的版本声明不低于 2.4，否则默认关闭 EL 表达式支持。
注解不生效或参数绑定异常
若 @Controller 和 @RequestMapping 注解未生效，首先确认是否在 Spring 配置文件中添加了 <mvc:annotation-driven/>，该标签会注册默认的处理器映射和处理器适配器。如果使用纯 Java 配置，则需要用 @EnableWebMvc 注解替代。此外，方法参数中的 Model、HttpServletRequest 等对象由框架自动注入，但如果方法参数顺序错误或使用了不支持的参数类型，可能抛出异常，请检查控制器方法签名。
中文乱码问题
在 JSP 页面和控制器中处理中文字符时，务必在页面头部声明 <%@ page contentType="text/html;charset=UTF-8" %>，并在 web.xml 中配置字符编码过滤器（CharacterEncodingFilter），强制请求和响应使用 UTF-8 编码。否则表单提交的中文数据可能出现乱码。
对比 XML 配置与注解配置
传统 Spring MVC 项目既可以使用 XML 配置（如本文示例），也可以使用纯 Java 配置。XML 配置直观但文件较多，注解配置（配合 WebApplicationInitializer）则更加精简，适合新项目。理解两者的差异有助于维护旧系统。无论采用哪种方式，核心的 DispatcherServlet 和组件扫描逻辑是一致的。
最后提醒一点：在开发阶段频繁重启 Tomcat 会影响效率，建议使用 IDE 的热部署插件（如 JRebel 或 Spring Boot DevTools）。如果坚持使用传统方式，也可以通过配置 Tomcat 的 Context 实现自动重新加载类。
Spring MVCHello World注解驱动修改时间：2026-09-27 16:45:23