在Java Web应用的部署描述符web.xml中，error-page元素用于配置当应用发生指定错误时跳转的页面，其中的location子元素就是用来指定自定义错误页面的路径，正确配置该属性可以让应用在出错时展示符合预期的友好页面。
error-page配置的基本结构
error-page元素可以配置两种类型的错误匹配规则，一种是匹配HTTP状态码，另一种是匹配Java异常类型，两种规则下location的配置要求基本一致。
匹配HTTP状态码的配置
当需要针对特定的HTTP错误状态码配置自定义页面时，使用error-code子元素指定状态码，location指定页面路径，配置示例如下：
<?xml version="1.0" encoding="UTF-8"?>
<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">
<!-- 配置404错误自定义页面 -->
<error-page>
<error-code>404</error-code>
<location>/error/404.jsp</location>
</error-page>
<!-- 配置500错误自定义页面 -->
<error-page>
<error-code>500</error-code>
<location>/error/500.jsp</location>
</error-page>
</web-app>
匹配异常类型的配置
当需要针对特定的Java异常配置自定义页面时，使用exception-type子元素指定异常的全类名，location指定页面路径，配置示例如下：
<error-page>
<exception-type>java.lang.NullPointerException</exception-type>
<location>/error/null_pointer.jsp</location>
</error-page>
<error-page>
<exception-type>java.io.IOException</exception-type>
<location>/error/io_error.jsp</location>
</error-page>
location路径的书写规则
location配置的路径需要遵循Servlet规范的要求，否则会导致错误页面无法正确加载：
- 路径必须以斜杠
/开头，这个斜杠代表当前Web应用的根目录，也就是webapp目录（如果是Maven项目则是src/main/webapp目录）。 - 路径指向的页面需要在Web应用的可访问目录下，通常我们会把错误页面统一放在webapp下的error目录中，方便管理。
- 路径中不能包含协议、域名、端口等信息，只需要写应用内部的相对路径即可，比如不需要写
http://localhost:8080/project/error/404.jsp，只需要写/error/404.jsp。 - 如果错误页面是JSP文件，直接写JSP文件的路径即可；如果是HTML文件，同样写HTML文件的路径，比如
/error/404.html。
自定义错误页面的示例代码
以404错误页面为例，我们可以在webapp/error目录下创建404.jsp文件，内容如下：
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<head>
<title>页面不存在</title>
</head>
<body>
<h1>抱歉，您访问的页面不存在</h1>
<p>请检查您输入的网址是否正确，或者返回<a href="/index.jsp">首页</a>继续浏览</p>
</body>
</html>
注意上面的标签是在代码块内部，符合配置要求，在实际运行的JSP页面中也可以正常使用链接跳转。
常见配置问题排查
如果配置完成后错误页面没有生效，可以按照以下步骤排查：
- 检查location路径是否以斜杠开头，很多开发者容易漏写开头的斜杠，导致路径解析错误。
- 检查路径指向的页面文件是否真实存在，比如配置的是
/error/404.jsp，就要确认webapp/error目录下是否有404.jsp文件。 - 检查error-page的配置是否放在web.xml的正确位置，需要放在servlet、filter等配置之后，但是要在其他非核心配置之前，不过大部分情况下位置不影响生效，只要格式正确即可。
- 如果是匹配异常类型的配置，检查exception-type中的异常类全名是否正确，不要写错包名或者类名。
注意事项
当错误页面本身也发生错误时，要避免出现无限跳转的情况，比如不要在500错误的自定义页面中再触发可能抛出500错误的逻辑。另外，如果项目使用了Spring MVC等框架，框架可能会有自己的错误页配置，需要注意和web.xml的配置优先级，通常web.xml的配置优先级更高，会优先生效。
error-pagelocationweb.xml自定义错误页面修改时间：2026-07-06 19:33:12