内容摘要:本文以一个已完成的 nginx 站点改造为案例,说明如何把 39 个常见 http 4xx/5xx 错误页面集中放入独立目录,用一份公共配置和每个站点一次 include 实现统一维护。文中使用 ***.com 脱敏域名,覆盖配置机制、部署验证、api 边界、失败路径和回滚方法,读者可据此在其他机器复用这套方案。
读者问题与范围
当多个域名各自维护 403.htm、404.htm 和对应的 error_page 时,页面更新容易遗漏,站点配置也会逐渐出现重复规则。本案例的核心问题是:如何把错误页面和路径配置集中到一个目录,同时不改变业务白名单、代理、证书和 api 的原有行为。
本文讨论 nginx 自身产生的 html 错误页,适用于网站页面和由 nginx 直接拒绝的请求。它不把后端 api 的 json 错误统一改成 html,也不处理 tls 握手失败、客户端主动断开等没有可展示 http 正文的情况。
核心判断与证据边界
核心判断
推荐使用“公共错误页目录 + 一份公共配置 + 每个 server 引用一次”的结构:
/etc/nginx/error-pages/ ├── error-pages.conf ├── html/ │ ├── 400.htm │ ├── 403.htm │ ├── 404.htm │ └── 其他错误页面 └── 接入说明.md
每个站点只保留一行:
include /etc/nginx/error-pages/error-pages.conf;
页面目录和 uri 的对应关系只在公共配置顶部定义一次。之后换页面只更新 html/,修改存放路径只修改 alias,不需要逐个改域名配置。
已验证事实
案例站点使用脱敏后的 ***.com 表示,实际验证覆盖了以下行为:
| 验证项 | 结果 | 证据范围 |
|---|---|---|
| 正常首页访问 | http 200 | 公网请求验证 |
| 白名单拒绝请求 | http 403,正文与 403.htm 一致 | 受保护路径验证 |
| 不存在页面 | http 404,正文与 404.htm 一致 | 不存在 uri 验证 |
| 直接访问内部错误页 | http 404 | internal 规则验证 |
| nginx 配置检查 | nginx -t 成功 | 生产配置检查 |
| 服务状态 | systemctl is-active nginx 为 active | 重载后状态检查 |
| 页面同步 | 39 个页面与本地版本匹配 | 文件内容校验 |
这些证据证明了该站点的配置和可安全触发的错误链路;它们不能推导所有后端应用错误都会被替换,也不能证明 408、444、499 或 tls 错误一定能展示 html。
配置机制:为什么公共文件要在server中引用
公共配置中同时包含 error_page 和 location:
# 页面目录:更换路径只需修改这一处,保留末尾斜杠。
location ^~ /_nginx-errors/ {
alias /etc/nginx/error-pages/html/;
internal;
allow all;
charset utf-8;
}
error_page 403 /_nginx-errors/403.htm;
error_page 404 /_nginx-errors/404.htm;
error_page 500 /_nginx-errors/500.htm;
alias 把内部 uri 映射到本地页面目录;internal 禁止客户端直接读取这些 uri,只允许 nginx 的内部错误跳转使用;不使用 =200,因此原错误状态码仍然保留。
location 只能出现在 server 或更深层上下文中。因此不能简单把下面这行放到 http 中:
http {
include /etc/nginx/error-pages/error-pages.conf;
}
否则会因为 location 上下文不合法而检查失败。正确做法是把公共文件放进每个目标 server:
server {
listen 443 ssl;
server_name ***.com;
# 原有证书、白名单、代理和业务路由保持不变
include /etc/nginx/error-pages/error-pages.conf;
}
这不是重复维护:站点首次接入时增加一行,错误码映射和页面路径之后都集中在公共文件中。
页面集合与状态码边界
当前套装包含 39 个页面:
400、401、403、404、405、406、407、408、409、410、411、412、413、414、415、416、417、418、 421、422、423、424、425、426、428、429、431、451、500、501、502、503、504、505、506、507、 508、510、511
页面沿用统一的黑白灰视觉模板:白底、居中内容、大号错误码、系统字体和本地内嵌样式,不依赖外部资源。错误文案按状态码解释用户可执行的下一步;403 的“连接可信网络”只适合白名单或网络隔离场景。
这里的“完整”指覆盖常见及扩展的 4xx/5xx 网页错误场景,并不等同于所有 nginx 内部事件。以下情况需要单独看待:
444、499、tls 握手失败和客户端主动断开,通常没有可返回的 html 响应。- 408 在部分超时路径中会被 nginx 直接关闭连接,不能保证展示页面。
- 请求解析阶段的某些 400、414 可能发生在虚拟主机选定之前,未必由目标站点的
server接管。 - 后端应用返回的 4xx/5xx 默认不经过本套装,除非在对应代理位置显式使用
proxy_intercept_errors on。
部署链路:从文件到可用页面
以下部署命令为脱敏示意,需要替换目录、站点配置文件名和域名后执行;***.com 是隐私占位符,不是真实可验证地址。案例配置与 403/404 请求已执行验证,但这里的命令文本未在新机器执行。案例未记录 nginx 的具体版本号,不据此承诺所有版本兼容。
1. 检查目标站点
先确认实际加载的站点和已有错误规则:
sudo nginx -t sudo rg -n "server_name|error_page|location.*403|location.*404|/etc/nginx/html" /etc/nginx
需要记录目标 server、已有同名 error_page、精确匹配的错误页 location 以及 api 是否要求 json。已有规则不能与公共文件重复,否则后续定位会变得困难。
2. 备份
备份站点配置和旧页面,目录放在 nginx 不会自动加载的位置:
backup="/etc/nginx/backups/error-pages-$(date +%y%m%d-%h%m%s)"
sudo mkdir -p "$backup"
sudo cp -a /etc/nginx/conf.d/站点配置.conf "$backup/"
if [ -d /etc/nginx/html ]; then
sudo cp -a /etc/nginx/html "$backup/"
fi
if [ -d /etc/nginx/error-pages ]; then
sudo cp -a /etc/nginx/error-pages "$backup/"
fi
3. 上传统一目录
把本地 error-pages/ 目录整体复制到 /etc/nginx/:
sudo mkdir -p /etc/nginx/error-pages
sudo cp -a error-pages/. /etc/nginx/error-pages/
sudo find /etc/nginx/error-pages -type f -exec chmod 644 {} \;
sudo find /etc/nginx/error-pages -type d -exec chmod 755 {} \;
上传到临时目录再移动也可以,但要避免在生产目录中留下半套文件。页面文件需要可读,目录需要可遍历;实际部署还应按发行版检查 selinux 或其他安全上下文。
4. 替换站点中的旧规则
把站点原本单独维护的配置:
error_page 403 /403.htm;
location = /403.htm {
internal;
root /etc/nginx/html;
allow all;
}
替换成:
include /etc/nginx/error-pages/error-pages.conf;
白名单、证书、代理、静态资源和业务路由保持不变。
5. 检查并重载
sudo nginx -t sudo systemctl reload nginx sudo systemctl is-active nginx
只有 nginx -t 成功后才重载。reload 会平滑切换 worker,不需要停止生产服务。
失败路径与反例
把公共文件直接 include 到http
由于文件包含 location,这样做会触发上下文错误。只有不含 location 的纯 error_page 映射才适合放在 http;本案例选择完整公共文件,因此在 server 中引用。
仍然保留旧的精确匹配 location
旧的 location = /403.htm 与新内部前缀是不同 uri,可能留下失效的旧目录引用;同名 location 重复则会导致配置检查失败。接入时应移除本次替代的旧规则,并用 nginx -t 检查最终配置。
给 api 全局开启proxy_intercept_errors
这会把上游返回的 json 错误替换成 html,破坏调用方契约。统一 html 错误页只处理 nginx 自身产生的错误;api 要求统一错误格式时,应单独设计 json 错误响应。
把所有 403 都写成网络限制
403 也可能代表账号、角色或资源权限不足。站点如果不是 ip 白名单场景,应更换文案,否则用户会得到错误的排障方向。
只替换页面但忘记配置
html 文件可以在运行时被读取,但新增错误码或修改 alias 属于配置变化,必须重新执行 nginx -t 并 reload。页面文件和配置不是一个原子版本,整套切换需要先上传、再检查、最后重载。
验证证据与回滚
安全验证
curl -i https://***.com/ curl -i https://***.com/不存在的地址 curl -i https://***.com/_nginx-errors/403.htm
预期分别取决于业务状态;关键断言是:触发 403/404 时状态码不变、正文与对应文件一致;直接访问内部 uri 返回 404。
如需核对正文:
curl -ss https://***.com/不存在的地址 -o /tmp/error-body.htm cmp /tmp/error-body.htm /etc/nginx/error-pages/html/404.htm
验证结论的边界
已证明:公共路径映射、内部访问保护、可触发的 403/404 链路和服务重载结果。未证明:所有上游应用错误、所有解析阶段错误以及无法正常返回 http 正文的连接事件。下一步应在隔离环境中按站点真实规则测试 500/502/503/504,并确认 api 响应契约不变。
回滚
sudo cp -a /etc/nginx/backups/备份目录/站点配置.conf /etc/nginx/conf.d/ sudo nginx -t sudo systemctl reload nginx
如果回滚前存在旧版公共目录,应同时恢复备份的 error-pages/;如果原站点依赖 /etc/nginx/html/,也必须先恢复该目录。恢复全部依赖后再检查与重载。
确认没有站点继续引用公共目录后,再清理 /etc/nginx/error-pages/。回滚后重新验证正常访问、403 和 404。
维护建议与结论
页面内容更新通常只替换对应 .htm,不需要 reload;改 error-pages.conf 的路径或映射时必须先检查再 reload。新增域名只需在其 server 中添加一行 include,不再复制几十行错误规则。
这个方案的价值不是把所有错误都“美化”为网页,而是把错误页的展示层与业务访问控制、后端错误契约分开:nginx 负责它自己能确定的错误,应用继续负责 api 语义,站点配置只保留接入点。对于需要 json、不同权限语义或复杂认证流程的站点,应采用独立规则,而不是无差别套用。
结论:在多个域名共享错误页的场景下,独立目录加公共 server 级配置是更易维护、可回滚且边界清晰的实现;部署前清理旧规则,部署后以状态码、正文匹配和内部 uri 保护作为验收标准。
以上就是nginx统一错误页面配置与落地实践的详细内容,更多关于nginx统一错误页面配置与落地的资料请关注代码网其它相关文章!
发表评论