在Java Web应用里，部署描述符web.xml通过welcome-file-list元素定义访问Web应用根目录或未指定具体资源时的默认欢迎页面。很多初学者以为它只是简单地列出index.html、index.jsp，实际上它的匹配机制和容器实现细节直接影响请求能否正确落地。理解这套机制，能避免部署后访问首页出现404的尴尬。
welcome-file-list的基本结构
welcome-file-list必须放在web.xml的合适位置，通常位于servlet和servlet-mapping定义之后，但规范并未强制严格顺序。它内部包含一个或多个welcome-file子元素，每个子元素填写一个候选文件名或路径片段。容器收到对目录（如斜杠结尾的请求）的访问时，会按声明顺序依次尝试这些候选。
需要注意的是，welcome-file中填写的路径不能以斜杠开头。如果写成<welcome-file>/index.html</welcome-file>，在Tomcat等常见容器中会被直接忽略，因为规范约定它是相对于当前目录的资源名。下面是一段最基础的配置示例：
<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_3_1.xsd"
version="3.1">
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>index.jsp</welcome-file>
<welcome-file>home.jsp</welcome-file>
</welcome-file-list>
</web-app>
以上配置表示：当用户访问应用上下文根（例如http://localhost:8080/myapp/）时，容器先找index.html，不存在就找index.jsp，再不存在就找home.jsp。如果全部缺失，容器可能返回404，或者由DefaultServlet决定行为。
匹配规则与容器行为差异
servlet规范指出，welcome-file可以是文件，也可以是映射到Servlet的路径。例如配置welcome-file为app/home，若web.xml中存在对应url-pattern为/app/home的Servlet映射，容器就会把根请求交给该Servlet处理。这在使用前端控制器（如Spring MVC的DispatcherServlet）时非常实用。
不过不同容器实现略有差异。Tomcat在寻找欢迎文件时，会先检查是否存在对应的静态文件，如果不存在再尝试将其作为Servlet路径调度。而有些老旧容器只认静态文件。因此生产环境建议同时提供静态兜底页和Servlet映射，并充分测试。以下示例展示如何结合Spring MVC使用：
<servlet>
<servlet-name>dispatcher</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>dispatcher</servlet-name>
<url-pattern>/app/*</url-pattern>
</servlet-mapping>
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>app/home</welcome-file>
</welcome-file-list>
上述配置中，app/home不会带斜杠，容器会将其当作相对于根的请求路径，从而命中/app/*的映射，最终由DispatcherServlet分发给home对应的控制器。若index.html存在则优先展示静态页，适合做门户引流。
常见误区与排错思路
第一个误区是认为welcome-file只能写后缀名固定的页面。实际上它可以没有后缀，只要能对应上资源或映射即可。第二个误区是在文件路径前加斜杠，如前所述，这会让Tomcat跳过该条目。第三个误区是以为配置了welcome-file-list就一定能覆盖所有目录访问，其实它只对“目录请求”生效，如果请求明确带了其他文件名则不适用。
排错时，可以打开容器日志观察DefaultServlet或Mapper的调试信息。例如在Tomcat中开启Fine级别日志，能看到它依次尝试welcome-file的过程。另外，使用curl -I http://127.0.0.1:8080/myapp/ 查看返回状态，若返回404且日志无匹配记录，多半是路径带斜杠或文件确实缺失。下面是一段简单的Java Servlet作为欢迎页兜底的处理片段：
@WebServlet("/app/home")
public class HomeServlet extends HttpServlet {
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws IOException {
resp.setContentType("text/html;charset=UTF-8");
resp.getWriter().write("<h1>欢迎来到首页</h1>");
}
}
该Servlet通过注解映射，无需在web.xml重复声明servlet-mapping，只要welcome-file写了app/home，根请求便可命中。这种写法在Servlet 3.0以上容器广泛支持，减少了配置冗余。
与框架默认页的协作建议
在Spring Boot兴起后，很多项目不再写web.xml，而是用Java Config或默认静态资源规则。但在传统War包项目中，web.xml仍是标准。建议将welcome-file-list视作“最后兜底”，真正的路由交给前端控制器。这样既能兼容旧容器，又不破坏框架的统一请求处理链。
如果项目同时使用安全约束（security-constraint），还要注意欢迎页本身是否被保护。若根路径需登录才能看，而welcome-file指向公开静态页，则容器可能在转发时触发认证跳转，造成体验异常。此时应将欢迎页也纳入放行列表，或统一由认证后的控制器渲染。
| 配置方式 | 适用场景 | 注意点 |
|---|---|---|
| 纯静态文件名 | 传统多页应用 | 文件必须真实存在 |
| Servlet路径 | 前端控制器架构 | 不要以斜杠开头 |
| 混合配置 | 兼容兜底 | 顺序影响优先级 |
综上所述，welcome-file-list并非简单罗列首页，它是一套容器级的请求兜底机制。理清匹配顺序、路径写法和容器差异，才能稳妥地配置出符合预期的默认欢迎页面。
web.xmlwelcome-file-list默认欢迎页修改时间：2026-08-10 11:30:47