当前位置: 代码网 > it编程>数据库>Oracle > Nginx统一错误页面配置与落地实践

Nginx统一错误页面配置与落地实践

2026年11月17日 • Oracle •我要评论
内容摘要:本文以一个已完成的 nginx 站点改造为案例,说明如何把 39 个常见 http 4xx/5xx 错误页面集中放入独立目录,用一份公共配置和每个站点一次 include 实现统一维护。文中

内容摘要:本文以一个已完成的 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 404internal 规则验证
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统一错误页面配置与落地的资料请关注代码网其它相关文章!

赞 (0)

相关文章:

版权声明:本文内容由互联网用户贡献,该文观点仅代表作者本人。本站仅提供信息存储服务,不拥有所有权,不承担相关法律责任。 如发现本站有涉嫌抄袭侵权/违法违规的内容, 请发送邮件至 2386932994@qq.com 举报,一经查实将立刻删除。

发表评论

验证码:
Copyright © 2017-2026  代码网 保留所有权利. 粤ICP备2024248653号
站长QQ:2386932994 | 联系邮箱:2386932994@qq.com