Nginx自定义错误页面样式与内容的配置方法

更新时间：2026年07月14日 08:34:56 作者：知远漫谈

当后端服务异常、资源未找到、请求超时或权限被拒绝时,Nginx 会返回默认的错误页面,本文将带你从零开始,深入掌握 Nginx 错误页面的自定义全流程,需要的朋友可以参考下

引言

在现代 Web 应用的架构中，Nginx 作为高性能的反向代理服务器和静态资源服务器，承担着至关重要的角色。它不仅负责请求的负载均衡、缓存加速、SSL 终止，更在用户与系统交互的“第一道门”上扮演着守护者与引导者的角色。当后端服务异常、资源未找到、请求超时或权限被拒绝时，Nginx 会返回默认的错误页面——这些页面通常由纯文本或极简 HTML 构成，缺乏品牌一致性，甚至可能让用户感到困惑、不安，甚至直接流失。

🚫 默认的 404 页面：“404 Not Found”
✅ 自定义的 404 页面：“哎呀，您寻找的页面似乎迷路了 🌌 我们正在努力找回它！”

这不仅是美观问题，更是用户体验（UX）设计与品牌信任建设的核心环节。一个精心设计的错误页面，能够将用户的负面情绪转化为耐心与好感，甚至引导他们继续探索你的产品。本文将带你从零开始，深入掌握 Nginx 错误页面的自定义全流程——包括配置原理、静态资源部署、动态内容生成、Java 后端联动、多语言支持、响应式样式设计、性能优化与监控策略，最终构建出一个既专业又富有温度的错误响应体系。

为什么我们需要自定义错误页面？

在讨论“如何做”之前，我们先明确“为什么必须做”。

1. 用户体验的“第一印象”是关键

根据 Google 的研究，用户在 0.5 秒内就会对网站的专业性形成初步判断。当用户点击一个链接，却看到一个冰冷的“404 Not Found”页面，他们的第一反应是：

“这个网站是不是已经废弃了？”
“是不是我点错了？”
“这家公司的技术是不是很落后？”

而一个设计精良、带有品牌元素、提供导航建议、甚至幽默文案的错误页面，则能：

减少跳出率 📉
增强品牌亲和力 ❤️
引导用户回到核心路径 🧭

2. 品牌一致性不容忽视

企业网站、SaaS 平台、API 服务，都应保持统一的视觉语言。默认的 Nginx 错误页使用的是系统字体、灰白配色、无 Logo、无链接，完全脱离了你的品牌体系。自定义错误页是品牌露出的“隐形窗口”。

3. 安全与信息控制

默认错误页面可能暴露服务器版本、操作系统、模块信息（如 Server: nginx/1.20.1），这为攻击者提供了可利用的指纹信息。通过自定义，我们可以：

隐藏服务器指纹
不暴露后端技术栈
避免泄露内部路径结构

4. 多语言与国际化支持

如果你的用户遍布全球，仅提供英文错误页是远远不够的。通过 Nginx 与后端 Java 服务的联动，我们可以实现基于 Accept-Language 请求头的动态错误页面，为中文、日文、德文用户提供本地化体验。

5. 监控与分析的入口

自定义错误页可以嵌入轻量级的埋点代码，记录用户访问错误页的时间、来源 URL、设备类型、地理位置等信息，为运维团队提供宝贵的用户行为分析数据，帮助发现死链、爬虫攻击、API 调用异常等问题。

Nginx 错误页面的底层机制

Nginx 通过 error_page 指令实现错误页面的重定向与自定义。这个指令的本质是：当发生指定 HTTP 状态码时，Nginx 将请求内部重定向到另一个 URI，由该 URI 返回的内容作为最终响应。

基础语法

error_page code [...] [=[response]] uri;

code：HTTP 状态码，如 404、500、502 等
uri：目标路径，可以是本地文件、内部重定向、或外部 URL
[=response]：可选，用于修改返回的状态码（如将 404 改为 200）

示例配置

server {
    listen 80;
    server_name example.com;
    # 自定义 404 页面
    error_page 404 /error/404.html;
    # 自定义 500 页面，同时修改返回状态码为 200（用于前端 SPA 处理）
    error_page 500 502 503 504 =200 /error/5xx.html;
    # 静态资源根目录
    root /var/www/html;
    location /error/ {
        alias /var/www/errors;
        internal;  # 仅允许内部重定向访问，禁止直接访问
    }
    location / {
        try_files $uri $uri/ =404;
    }
}

关键点解析

指令	作用
`error_page 404 /error/404.html;`	当发生 404 时，Nginx 内部跳转到 `/error/404.html`
`alias /var/www/errors;`	将 `/error/` 路径映射到服务器上的 `/var/www/errors` 目录
`internal;`	非常重要！确保用户无法直接通过浏览器访问 `/error/404.html`，防止绕过逻辑
`=200`	将 5xx 错误的响应状态码改为 200，适用于前端单页应用（SPA）框架统一处理错误

⚠️ 注意：internal 指令是安全最佳实践。若不设置，攻击者可能通过访问 /error/500.html 获取你的错误页面模板，进而推测系统架构。

构建静态错误页面：HTML + CSS + JS

我们先从最基础的静态方式开始。假设我们希望为 404、500、502 分别设计独立页面。

文件结构规划

/var/www/errors/
├── 404.html
├── 500.html
├── 502.html
├── css/
│   └── error.css
├── js/
│   └── error.js
└── assets/
    ├── logo.svg
    └── illustration.png

提示：虽然我们不使用图片链接，但你可以使用 SVG 内联方式嵌入矢量图形，既轻量又无外部依赖。

404 页面示例：/var/www/errors/404.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>页面找不到了 😅</title>
    <link rel="stylesheet" href="/error/css/error.css" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >
    <style>
        /* 内联关键样式，确保即使 CSS 加载失败也能基本可读 */
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            background-color: #f8f9fa;
            color: #333;
            text-align: center;
            padding: 4rem 1rem;
            margin: 0;
        }
        .error-container {
            max-width: 600px;
            margin: 0 auto;
        }
        .emoji {
            font-size: 8rem;
            margin: 1rem 0;
        }
        h1 {
            font-weight: 600;
            font-size: 2.5rem;
            color: #555;
        }
        p {
            font-size: 1.2rem;
            line-height: 1.6;
            color: #666;
            margin: 1.5rem 0;
        }
        .btn {
            display: inline-block;
            background: #007bff;
            color: white;
            padding: 0.8rem 1.5rem;
            text-decoration: none;
            border-radius: 50px;
            font-weight: 600;
            margin: 0.8rem;
            transition: background 0.3s;
        }
        .btn:hover {
            background: #0056b3;
        }
        .footer {
            margin-top: 3rem;
            font-size: 0.9rem;
            color: #999;
        }
    </style>
</head>
<body>
    <div class="error-container">
        <div class="emoji">🔍</div>
        <h1>页面不见了</h1>
        <p>抱歉，您访问的页面可能已被移除、改名，或暂时无法访问。</p>
        <p>您可以尝试：</p>
        <ul style="text-align: left; display: inline-block; margin: 1.5rem auto; font-size: 1.1rem;">
            <li>👉 返回 <a href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  style="color: #007bff; text-decoration: none;">首页</a></li>
            <li>👉 检查网址拼写</li>
            <li>👉 使用顶部搜索框查找内容</li>
        </ul>
        <a href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn">回到首页</a>
        <a href="/contact" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn" style="background: #6c757d;">联系我们</a>
        <div class="footer">
            © 2025 YourCompany Inc. · 服务热线：400-123-4567
        </div>
    </div>
    <script src="/error/js/error.js"></script>
    <script>
        // 记录 404 访问事件（发送到后端分析服务）
        document.addEventListener('DOMContentLoaded', function() {
            fetch('/api/analytics/error', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    type: '404',
                    url: window.location.href,
                    referrer: document.referrer,
                    userAgent: navigator.userAgent,
                    timestamp: new Date().toISOString()
                })
            }).catch(console.error);
        });
    </script>
</body>
</html>

500 页面示例：/var/www/errors/500.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>服务器有点累了 🛠️</title>
    <link rel="stylesheet" href="/error/css/error.css" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >
    <style>
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            background-color: #f8f9fa;
            color: #333;
            text-align: center;
            padding: 4rem 1rem;
            margin: 0;
        }
        .error-container {
            max-width: 600px;
            margin: 0 auto;
        }
        .emoji {
            font-size: 8rem;
            margin: 1rem 0;
            color: #dc3545;
        }
        h1 {
            font-weight: 600;
            font-size: 2.5rem;
            color: #555;
        }
        p {
            font-size: 1.2rem;
            line-height: 1.6;
            color: #666;
            margin: 1.5rem 0;
        }
        .btn {
            display: inline-block;
            background: #28a745;
            color: white;
            padding: 0.8rem 1.5rem;
            text-decoration: none;
            border-radius: 50px;
            font-weight: 600;
            margin: 0.8rem;
            transition: background 0.3s;
        }
        .btn:hover {
            background: #218838;
        }
        .footer {
            margin-top: 3rem;
            font-size: 0.9rem;
            color: #999;
        }
        .retry {
            animation: pulse 2s infinite;
        }
        @keyframes pulse {
            0% { transform: scale(1); }
            50% { transform: scale(1.05); }
            100% { transform: scale(1); }
        }
    </style>
</head>
<body>
    <div class="error-container">
        <div class="emoji">💥</div>
        <h1>服务器出了一点小状况</h1>
        <p>我们正在努力修复这个问题。请稍后再试，或联系我们的支持团队。</p>
        <p><small>错误代码：500 Internal Server Error</small></p>
        <a href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn">返回首页</a>
        <a href="/contact" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn" style="background: #6c757d;">获取帮助</a>
        <div class="footer">
            © 2025 YourCompany Inc. · 我们承诺 99.9% 的服务可用性
            <span class="retry">🔄 自动重试中…</span>
        </div>
    </div>
    <script src="/error/js/error.js"></script>
    <script>
        // 500 页面自动重试机制（5秒后尝试刷新）
        setTimeout(() => {
            if (confirm('系统正在尝试恢复，是否立即刷新页面？')) {
                window.location.reload();
            }
        }, 5000);
        // 上报错误事件
        document.addEventListener('DOMContentLoaded', function() {
            fetch('/api/analytics/error', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                    type: '500',
                    url: window.location.href,
                    referrer: document.referrer,
                    userAgent: navigator.userAgent,
                    timestamp: new Date().toISOString()
                })
            }).catch(console.error);
        });
    </script>
</body>
</html>

CSS 与 JS 公共资源

/var/www/errors/css/error.css

/* 公共错误页样式 */
body {
    margin: 0;
    padding: 0;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
    background-color: #f8f9fa;
    color: #333;
}
.error-container {
    max-width: 700px;
    margin: 0 auto;
    padding: 2rem;
    background: white;
    border-radius: 12px;
    box-shadow: 0 10px 30px rgba(0,0,0,0.08);
}
.emoji {
    font-size: 6rem;
    margin: 1.5rem 0;
}
h1 {
    font-weight: 700;
    font-size: 2.2rem;
    margin: 1rem 0;
}
p {
    font-size: 1.1rem;
    line-height: 1.7;
    color: #555;
    margin: 1.5rem 0;
}
.btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    background: #007bff;
    color: white;
    padding: 0.75rem 1.5rem;
    text-decoration: none;
    border-radius: 30px;
    font-weight: 600;
    font-size: 1rem;
    margin: 0.5rem;
    border: none;
    cursor: pointer;
    transition: all 0.3s ease;
    box-shadow: 0 4px 10px rgba(0,123,255,0.25);
}
.btn:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 15px rgba(0,123,255,0.35);
}
.btn:active {
    transform: translateY(0);
}
.footer {
    margin-top: 3rem;
    font-size: 0.9rem;
    color: #888;
    line-height: 1.5;
}
@media (max-width: 768px) {
    .error-container {
        padding: 1.5rem;
    }
    .emoji {
        font-size: 5rem;
    }
    h1 {
        font-size: 1.8rem;
    }
    p {
        font-size: 1rem;
    }
}

/var/www/errors/js/error.js

// 公共错误页脚本：统一埋点、语言检测、交互增强
(function() {
    // 检测用户语言偏好
    const lang = navigator.language || navigator.userLanguage;
    const supportedLangs = ['zh-CN', 'zh-TW', 'en-US', 'ja-JP', 'ko-KR'];
    const userLang = supportedLangs.find(l => lang.startsWith(l)) || 'en-US';
    // 可选：根据语言动态替换页面文本（需配合后端 i18n）
    if (userLang !== 'zh-CN') {
        document.documentElement.lang = userLang;
        // 可在此处通过 fetch 加载语言包，或由后端动态注入
    }
    // 埋点：记录错误页面访问
    function trackError(type) {
        const payload = {
            type: type,
            url: window.location.href,
            referrer: document.referrer,
            userAgent: navigator.userAgent,
            timestamp: new Date().toISOString(),
            language: userLang,
            screen: `${screen.width}x${screen.height}`,
            platform: navigator.platform
        };
        // 使用 beacon API 避免阻塞页面加载
        if (navigator.sendBeacon) {
            navigator.sendBeacon('/api/analytics/error', JSON.stringify(payload));
        } else {
            // 降级：使用 fetch，但不等待响应
            fetch('/api/analytics/error', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify(payload),
                keepalive: true
            }).catch(() => {});
        }
    }
    // 页面加载完成后上报
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', () => trackError('unknown'));
    } else {
        trackError('unknown');
    }
    // 绑定“返回首页”按钮事件
    document.querySelectorAll('.btn[href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" ]').forEach(btn => {
        btn.addEventListener('click', () => {
            trackError('click_home');
        });
    });
    // 绑定“联系我们”按钮事件
    document.querySelectorAll('.btn[href="/contact" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" ]').forEach(btn => {
        btn.addEventListener('click', () => {
            trackError('click_contact');
        });
    });
})();

Nginx + Java 动态错误页面：实现真正的智能响应

静态页面虽然优雅，但缺乏“智能”。我们能否根据用户语言、设备类型、访问来源、甚至用户身份，动态生成错误页面？

答案是：完全可以！

架构设计：Nginx → Java 微服务 → 动态 HTML

我们引入一个轻量级 Java 微服务，专门负责生成动态错误页面。Nginx 将所有错误请求重定向到 /error/dynamic，由 Java 服务处理并返回个性化内容。

用户请求 → Nginx → 404 → /error/dynamic → Java 服务 → 动态 HTML → 返回给用户

Java 服务：Spring Boot 错误页面生成器

我们创建一个独立的 Spring Boot 应用，仅用于处理 /error/dynamic 路径。

pom.xml（简化版）

<?xml version="1.0" encoding="UTF-8"?>
<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.yourcompany</groupId>
    <artifactId>error-page-service</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.thymeleaf.extras</groupId>
            <artifactId>thymeleaf-extras-java8time</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

application.yml

server:
  port: 8081
  servlet:
    context-path: /error
spring:
  thymeleaf:
    cache: false
    enabled: true
    prefix: classpath:/templates/
    suffix: .html
    mode: HTML
    encoding: UTF-8
logging:
  level:
    com.yourcompany: DEBUG

主启动类：ErrorPageApplication.java

package com.yourcompany.errorpage;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class ErrorPageApplication {
    public static void main(String[] args) {
        SpringApplication.run(ErrorPageApplication.class, args);
    }
}

控制器：ErrorController.java

package com.yourcompany.errorpage.controller;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import javax.servlet.http.HttpServletRequest;
import java.time.LocalDateTime;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;
@Controller
@RequestMapping("/dynamic")
public class ErrorController {
    @GetMapping
    public String handleError(
            Model model,
            HttpServletRequest request,
            @RequestHeader(value = "Accept-Language", required = false) String acceptLanguage,
            @RequestParam(value = "code", required = false) String errorCode,
            @RequestParam(value = "url", required = false) String requestedUrl,
            @RequestParam(value = "referer", required = false) String referer
    ) {
        // 解析状态码
        int status = Optional.ofNullable(errorCode)
                .map(Integer::parseInt)
                .orElse(500);
        // 解析语言
        Locale locale = Optional.ofNullable(acceptLanguage)
                .map(lang -> Locale.forLanguageTag(lang.split(",")[0].trim()))
                .orElse(Locale.ENGLISH);
        // 构建模型
        model.addAttribute("status", status);
        model.addAttribute("requestedUrl", requestedUrl);
        model.addAttribute("referer", referer);
        model.addAttribute("timestamp", LocalDateTime.now());
        model.addAttribute("locale", locale.getLanguage());
        model.addAttribute("userAgent", request.getHeader("User-Agent"));
        // 根据状态码选择模板
        switch (status) {
            case 404:
                return "error/404";
            case 500:
                return "error/500";
            case 502:
                return "error/502";
            case 503:
                return "error/503";
            default:
                return "error/generic";
        }
    }
}

模板：src/main/resources/templates/error/404.html（Thymeleaf）

<!DOCTYPE html>
<html lang="thymeleaf: ${locale}" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title th:text="#{error.404.title}">Page Not Found</title>
    <link rel="stylesheet" href="/error/css/error.css" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >
    <style>
        /* 同前文，保持样式一致 */
        body { font-family: 'Segoe UI', sans-serif; background: #f8f9fa; }
        .emoji { font-size: 8rem; margin: 1rem 0; }
        h1 { font-size: 2.5rem; color: #333; }
        p { color: #666; font-size: 1.2rem; }
        .btn { padding: 0.8rem 1.5rem; border-radius: 50px; }
    </style>
</head>
<body>
<div class="error-container">
    <div class="emoji">🔍</div>
    <h1 th:text="#{error.404.heading}">Page Not Found</h1>
    <p th:text="#{error.404.description}">The page you are looking for might have been removed, had its name changed, or is temporarily unavailable.</p>
    <ul style="text-align: left; display: inline-block; margin: 1.5rem auto; font-size: 1.1rem;">
        <li>👉 <a href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  th:text="#{error.404.link.home}">Home</a></li>
        <li>👉 <a href="/search" rel="external nofollow"  th:text="#{error.404.link.search}">Search</a></li>
        <li>👉 <a href="/contact" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  th:text="#{error.404.link.contact}">Contact Us</a></li>
    </ul>
    <a href="/" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn" th:text="#{error.404.btn.home}">Home</a>
    <a href="/contact" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  class="btn" style="background: #6c757d;" th:text="#{error.404.btn.contact}">Contact</a>
    <div class="footer">
        <p th:text="#{error.footer}">© 2025 YourCompany Inc. · Service Hotline: 400-123-4567</p>
        <p th:if="${requestedUrl}" th:text="|Requested: ${requestedUrl}|"></p>
        <p th:if="${referer}" th:text="|Referer: ${referer}|"></p>
    </div>
</div>
<script src="/error/js/error.js"></script>
<script th:inline="javascript">
    /*<![CDATA[*/
    document.addEventListener('DOMContentLoaded', function() {
        fetch('/api/analytics/error', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                type: [[${status}]],
                url: '[[${requestedUrl}]]',
                referrer: '[[${referer}]]',
                userAgent: navigator.userAgent,
                language: '[[${locale}]]',
                timestamp: new Date().toISOString()
            })
        }).catch(console.error);
    });
    /*]]>*/
</script>
</body>
</html>

国际化资源文件：src/main/resources/i18n/messages_zh_CN.properties

error.404.title=页面找不到
error.404.heading=页面不见了
error.404.description=抱歉，您访问的页面可能已被移除、改名，或暂时无法访问。
error.404.link.home=返回首页
error.404.link.search=使用搜索
error.404.link.contact=联系我们
error.404.btn.home=回到首页
error.404.btn.contact=获取帮助
error.footer=© 2025 YourCompany Inc. · 服务热线：400-123-4567

messages_en_US.properties

error.404.title=Page Not Found
error.404.heading=Page Not Found
error.404.description=The page you are looking for might have been removed, had its name changed, or is temporarily unavailable.
error.404.link.home=Home
error.404.link.search=Search
error.404.link.contact=Contact Us
error.404.btn.home=Go Home
error.404.btn.contact=Contact Support
error.footer=© 2025 YourCompany Inc. · Service Hotline: 400-123-4567

messages_ja_JP.properties

error.404.title=ページが見つかりません
error.404.heading=ページが見つかりませんでした
error.404.description=お探しのページは削除されたか、名前が変更されたか、一時的に利用できない可能性があります。
error.404.link.home=ホーム
error.404.link.search=検索
error.404.link.contact=お問い合わせ
error.404.btn.home=ホームへ戻る
error.404.btn.contact=サポートへ連絡
error.footer=© 2025 YourCompany Inc. · サポート電話：400-123-4567

✅ Thymeleaf 优势：支持国际化、条件渲染、安全转义、模板继承，完美替代传统 JSP。

Nginx 配置：将错误请求代理到 Java 服务

现在，我们修改 Nginx 配置，让所有错误请求都通过 proxy_pass 转发给 Java 服务。

server {
    listen 80;
    server_name example.com;
    # 静态资源根目录
    root /var/www/html;
    # 404 错误：代理到 Java 服务
    error_page 404 = @error_dynamic;
    # 5xx 错误：代理到 Java 服务，并修改状态码为 200（SPA 兼容）
    error_page 500 502 503 504 =200 @error_dynamic;
    # 处理后端请求
    location @error_dynamic {
        internal;  # 只允许内部调用
        # 构建动态请求参数
        set $err_code $status;
        set $err_url $request_uri;
        set $err_referer $http_referer;
        proxy_pass http://localhost:8081/error/dynamic?code=$err_code&url=$err_url&referer=$err_referer;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Accept-Language $http_accept_language;
        # 缓存策略：5xx 错误页面缓存 30 秒
        proxy_cache_valid 200 30s;
        proxy_cache_error 500 502 503 504 30s;
        proxy_cache_bypass $http_cache_control;
        proxy_cache_lock on;
        proxy_cache_lock_age 10s;
        proxy_cache_lock_timeout 5s;
        # 响应头：确保不缓存错误页面到客户端
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";
        add_header Expires "0";
    }
    # 静态错误页面 fallback（Java 服务宕机时使用）
    location /error/ {
        alias /var/www/errors;
        internal;
    }
    location / {
        try_files $uri $uri/ =404;
    }
}

Nginx 缓存策略详解

指令	作用
`proxy_cache_valid 200 30s;`	对 200 响应缓存 30 秒
`proxy_cache_error 500 502 503 504 30s;`	对 5xx 错误也缓存 30 秒（防止后端雪崩）
`proxy_cache_lock on;`	避免“缓存击穿”：多个请求同时命中未缓存资源时，只让一个请求去后端
`proxy_cache_bypass`	若客户端携带 `Cache-Control: no-cache`，则跳过缓存
`add_header Cache-Control "no-cache"`	告诉浏览器不要缓存错误页

✅ 重要：即使后端 Java 服务挂了，Nginx 仍能返回静态错误页（通过 location /error/），实现双保险机制。

多语言自动识别与用户偏好匹配

Java 服务通过 Accept-Language 请求头自动识别用户语言。但用户可能有多个语言偏好：

Accept-Language: zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7

Thymeleaf 会自动根据 LocaleResolver 选择最匹配的语言包。我们还可以在前端增强体验：

<!-- 在页面中动态显示当前语言 -->
<p th:text="'当前语言：' + ${locale}">当前语言：zh-CN</p>
<!-- 提供语言切换按钮（仅在用户未登录时显示） -->
<div th:if="${not #authentication.principal}" style="margin-top: 2rem;">
    <a href="?lang=zh-CN" rel="external nofollow"  style="margin-right: 1rem;">🇨🇳 中文</a>
    <a href="?lang=en-US" rel="external nofollow"  style="margin-right: 1rem;">🇺🇸 English</a>
    <a href="?lang=ja-JP" rel="external nofollow"  style="margin-right: 1rem;">🇯🇵 日本語</a>
</div>

💡 你可以结合 localStorage 记住用户偏好，下次访问时自动应用。

错误页面埋点与监控：Java 后端分析服务

为了让运维团队能实时监控错误页面的访问情况，我们在 Java 服务中添加一个独立的分析端点。

AnalyticsController.java

package com.yourcompany.errorpage.controller;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import java.time.LocalDateTime;
import java.util.Map;
@RestController
public class AnalyticsController {
    private static final Logger log = LoggerFactory.getLogger(AnalyticsController.class);
    @Value("${analytics.enabled:true}")
    private boolean analyticsEnabled;
    @PostMapping("/api/analytics/error")
    public void logError(@RequestBody Map<String, Object> payload) {
        if (!analyticsEnabled) return;
        log.info("ERROR ANALYTICS: {}", payload);
        // 可选：写入 Kafka、Elasticsearch、或发送到 Prometheus
        // 这里仅打印日志，实际项目中应异步写入数据库或消息队列
        // 示例：写入 CSV 日志文件
        // FileAppender.appendErrorLog(payload);
    }
}

日志输出示例

ERROR ANALYTICS: {
  "type": "404",
  "url": "/api/v1/user/12345",
  "referrer": "https://google.com/search?q=yourcompany+products",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X)",
  "language": "zh-CN",
  "timestamp": "2025-04-05T12:34:56.789Z",
  "screen": "375x812",
  "platform": "iPhone"
}

你可以将这些日志接入 ELK、Grafana Loki 或 Datadog，构建错误页面访问热力图：

测试与验证：如何确保配置正确？

1. 测试静态页面

curl -H "Accept-Language: zh-CN" http://localhost/error/404.html

应返回完整 HTML。

2. 测试 Nginx 动态代理

curl -H "Accept-Language: ja-JP" http://localhost/error/dynamic?code=404&url=/nonexistent

应返回日文内容。

3. 模拟 404 请求

curl -I http://localhost/nonexistent-path

检查响应头：

HTTP/1.1 404 Not Found
Server: nginx
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache, no-store, must-revalidate

4. 模拟 500 错误（测试 Java 服务）

在 Java 服务中临时抛出异常：

@GetMapping("/test/500")
public String test500() {
    throw new RuntimeException("Simulated 500 error");
}

访问 http://localhost:8081/error/dynamic?code=500，观察返回内容。

性能优化：如何让错误页更快？

错误页面的加载速度，直接影响用户流失率。以下是优化策略：

✅ 1. 内联关键 CSS

将首屏渲染必需的 CSS 直接写入 <style> 标签，避免阻塞渲染。

✅ 2. 使用 SVG 内联图标

<!-- 替代图片 -->
<svg width="120" height="120" viewBox="0 0 120 120" xmlns="http://www.w3.org/2000/svg">
  <circle cx="60" cy="60" r="50" fill="#f0f0f0"/>
  <path d="M40 40 L80 80 M80 40 L40 80" stroke="#ccc" stroke-width="4" fill="none"/>
</svg>

✅ 3. 压缩 HTML

在 Nginx 中启用 Gzip：

gzip on;
gzip_vary on;
gzip_min_length 1000;
gzip_types text/html application/json text/css application/javascript;

✅ 4. 使用 HTTP/2

确保 Nginx 启用 HTTP/2，提升多资源并发加载效率：

listen 443 ssl http2;

✅ 5. 预加载关键资源（可选）

<link rel="preload" as="style" href="/error/css/error.css" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >

安全加固：防止错误页成为攻击入口

1. 禁止直接访问错误页路径

location /error/ {
    alias /var/www/errors;
    internal;  # ⚠️ 必须设置！
}

2. 过滤恶意参数

在 Java 控制器中校验参数：

if (requestedUrl != null && requestedUrl.contains("..")) {
    requestedUrl = "/"; // 安全降级
}

3. 避免 XSS 注入

Thymeleaf 默认自动转义变量：

<p th:text="${requestedUrl}">...</p> <!-- 安全！ -->
<p th:utext="${requestedUrl}">...</p> <!-- 危险！不要用 -->

4. 隐藏服务器信息

server_tokens off;

5. 设置 CSP（内容安全策略）

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline';">

多语言、多地区、多设备：真正的全球化支持

你是否想过，一个在德国访问的用户，看到的错误页应该是德语？一个在印度使用安卓手机的用户，是否需要更简化的布局？

我们可以通过以下方式实现：

维度	实现方式
语言	`Accept-Language` 头 + Thymeleaf 国际化
地区	通过 IP 地理库（如 MaxMind）识别国家，返回本地化文案
设备	`User-Agent` 检测 → 移动端隐藏复杂按钮
登录状态	通过 Cookie 判断用户是否登录 → 显示“联系客服”按钮
时间	根据时区显示“请在工作时间联系我们”

// 示例：根据 IP 获取国家
@GetMapping("/dynamic")
public String handleError(Model model, HttpServletRequest request) {
    String clientIp = getClientIp(request);
    String country = geoService.getCountry(clientIp); // 如：CN, JP, DE
    model.addAttribute("country", country);
    // 根据国家加载不同文案
    if ("JP".equals(country)) {
        model.addAttribute("supportPhone", "0120-123-456");
    } else if ("DE".equals(country)) {
        model.addAttribute("supportPhone", "+49 30 12345678");
    }
}

监控与告警：当错误页访问激增时怎么办？

错误页面访问量的异常飙升，往往是系统问题的“前兆”。

场景	可能原因	建议响应
404 暴增	外部链接失效、爬虫抓取、API 路径变更	检查 Google Search Console、分析 referrer
500 暴增	后端服务崩溃、数据库连接池耗尽、缓存穿透	立即查看 JVM 日志、数据库慢查询
502 暴增	后端服务重启、负载均衡失效	检查后端健康检查、重启服务
503 暴增	限流触发、CDN 回源失败	检查 QPS、带宽、上游服务响应时间

告警规则示例（Prometheus + Alertmanager）

groups:
- name: error-page-alerts
  rules:
  - alert: High404Rate
    expr: rate(error_page_requests{type="404"}[5m]) > 10
    for: 1m
    labels:
      severity: warning
    annotations:
      summary: "404 错误率超过 10 次/分钟"
      description: "最近5分钟内，错误页面访问量达到 {{ $value }} 次/秒，可能有死链或爬虫攻击。"
  - alert: High5xxRate
    expr: rate(error_page_requests{type=~"500|502|503|504"}[5m]) > 5
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "5xx 错误率异常升高"
      description: "后端服务稳定性下降，需立即排查。"

扩展：动态生成 SVG 插画（无图版）

你可能希望错误页有插画，但不想使用图片链接。我们可以用 Java 动态生成 SVG 内容！

@GetMapping("/dynamic")
public String handleError(Model model) {
    String svg = """
        <svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
          <circle cx="100" cy="100" r="90" fill="#f0f0f0"/>
          <path d="M60,60 L140,140 M140,60 L60,140" stroke="#ccc" stroke-width="4" fill="none"/>
          <text x="100" y="180" text-anchor="middle" font-size="14" fill="#666">找不到？</text>
        </svg>
        """;
    model.addAttribute("customSvg", svg);
    return "error/404";
}

在模板中：

<div th:utext="${customSvg}"></div>

完全无外部依赖，体积小，可缩放，SEO 友好。

总结：构建企业级错误页面的最佳实践清单

类别	实践建议
✅ 设计原则	温暖、清晰、有引导、无恐慌
✅ 技术架构	Nginx + Java 动态渲染 + 静态 fallback
✅ 语言支持	Thymeleaf + 国际化资源文件
✅ 性能优化	内联 CSS、SVG 图标、Gzip、HTTP/2
✅ 安全加固	`internal` 指令、CSP、参数过滤、隐藏 server token
✅ 监控埋点	异步上报访问日志、集成分析平台
✅ 容灾设计	Java 服务宕机时，自动降级到静态页
✅ 全球化	支持 IP 地理定位、时区、本地联系方式
✅ 可维护性	模板与样式分离、版本控制、CI/CD 自动部署

结语：错误页面，是用户旅程的“温柔转折点”

我们常常把精力集中在首页、登录页、支付流程上，却忽略了那些“失败”的瞬间。但正是这些时刻，决定了用户是否愿意再给你一次机会。

一个精心设计的 404 页面，不只是一个“错误提示”，它是一次情感修复、一次品牌关怀、一次技术自信的展示。

“最好的错误页面，是让用户感觉‘不是我错了，而是系统在帮我’。”

当你看到一个用户在 404 页面停留了 12 秒，点击了“返回首页”，然后继续浏览——你就知道，你赢了。

这不是技术的胜利，是人性的胜利。

以上就是Nginx自定义错误页面样式与内容的配置方法的详细内容，更多关于Nginx自定义错误页面样式与内容的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

nginx基础配置说明一则
nginx基础配置说明一则，有需要的朋友可以参考下
2013-02-02
Nginx启用GZIP压缩网页传输方法(推荐)
Gzip压缩我很早已经就启用了，不过从未与大家分享过。今天小编给大家分享Nginx启用GZIP压缩网页传输方法，需要的朋友参考下吧
2017-01-01
实现nginx&php服务器配置的非主流配置方法
这种方法并非以前所流行的apache 加 php_module 的方式运行，我是采用nginx 作为web服务器，以fastcgi的方式运行php
2011-05-05
Ubuntu服务器已下载Nginx安装包的安装步骤(最新推荐)
在Ubuntu服务器上安装已下载的 Nginx,需完成依赖安装、解压编译、配置安装及服务验证等步骤,本文给大家介绍Ubuntu服务器已下载Nginx安装包的安装步骤,感兴趣的朋友跟随小编一起看看吧
2025-10-10
Nginx构建Tomcat集群的操作方法
nginx是一款自由的、开源的、高性能的HTTP服务器和反向代理服务器；同时也是一个IMAP、POP3、SMTP代理服务器，这篇文章主要介绍了Nginx构建Tomcat集群的问题,需要的朋友可以参考下
2022-01-01
Nginx几种负载均衡模式的实现示例
本文主要介绍了Nginx几种负载均衡模式的实现示例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2025-10-10
Nginx代理Partainer的具体使用
本文主要介绍了Nginx代理Partainer的具体使用，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2023-03-03
Nginx使用Lua模块实现WAF的原理解析
waf是通过执行一系列针对HTTP/HTTPS的安全策略来专门为Web应用提供保护的一款产品，本文重点给大家介绍Nginx使用Lua模块实现WAF的原理，需要的朋友参考下吧
2021-09-09
使用 nginx 搭建代理服务器(正向代理 https 网站)的详细步骤
这篇文章主要介绍了使用 nginx 搭建代理服务器（正向代理 https 网站）指南的相关操作,本文给大家介绍的非常详细,感兴趣的朋友跟随小编一起看看吧
2024-08-08
Nginx服务器Nginx.com配置文件详解
这篇文章主要介绍了Nginx服务器Nginx.com配置文件详解的相关资料,本文介绍的非常详细，具有参考借鉴价值，需要的朋友可以参考下
2016-09-09