Nginx & Caddy 错误页面拦截配置指南 🛡️

File Server Setup

🚨 本文详细介绍如何配置 Nginx 和 Caddy 服务器的错误页面拦截功能，提供用户友好的错误提示，提升网站用户体验。

📋 目录导航

✨ 核心功能特点

  • 🎯 错误拦截：自动捕获和处理各种HTTP错误状态码
  • 🎨 自定义页面：支持完全自定义的错误页面设计
  • 🔧 灵活配置：可根据不同错误类型设置不同处理方式
  • ⚡ 高性能：轻量级错误处理机制，不影响正常请求
  • 📱 响应式设计：错误页面适配各种设备屏幕

🛠️ 一、Nginx 错误页面配置

1. 📝 完整配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
server {
    ## 监听5553端口，并启用SSL
    listen 5553 ssl;
    listen [::]:5553 spcsl;

    ## 替换为你的域名
    server_name xunlei.mobufan.eu.org;

    ## 指定 SSL 证书文件和私钥文件的路径
    ssl_certificate /etc/nginx/keyfile/cert.pem;  
    ssl_certificate_key /etc/nginx/keyfile/key.pem;  
    
    location / {
        ## 指定反向代理的服务地址
        proxy_pass http://10.10.10.245:2345;  
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
        proxy_redirect off;
        proxy_buffering on; #开启缓存
        # 使用 HTTP/1.1 协议与后端服务器通信
        proxy_http_version 1.1;
        client_max_body_size 20000m;
    }
    
    ## 错误处理配置
    charset utf-8;  # 指定编码
    error_page 404 500 502 503 504 /50x.html;
    
    location = /50x.html {
        root /var/www/html;
        # 内部位置，防止直接访问
        internal;
        # 设置错误页面的MIME类型
        default_type text/html;
        # 禁用代理缓存错误页面
        proxy_no_cache 1;
        proxy_cache_bypass 1;
    }
}

2. 🔧 错误处理部分详解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
## 错误处理配置
charset utf-8;  # 确保正确显示中文
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;

# 404错误页面配置
location = /404.html {
    root /var/www/html;
    internal;
    # 设置缓存控制
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

# 50x错误页面配置
location = /50x.html {
    root /var/www/html;
    internal;
    # 允许跨域访问（如果需要）
    add_header Access-Control-Allow-Origin "*";
}

3. ⚡ 配置生效命令

1
2
3
4
5
6
7
8
# 检查Nginx配置语法
sudo nginx -t

# 重新加载Nginx配置
sudo nginx -s reload

# 或者使用systemctl
sudo systemctl reload nginx

🚀 二、Caddy 错误页面配置

1. 📝 完整配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
https://xunlei.meimolihan.eu.org:6663 {
    encode gzip
    tls ssl/full_chain.pem ssl/private.key
    
    # 反向代理配置
    reverse_proxy http://10.10.10.245:2345 {
        header_up Host {http.reverse_proxy.upstream.hostport}
        header_up X-Real-IP {remote_host}
    }
    
    ## 错误处理配置
    handle_errors {
        ## 将所有错误重定向到对应的错误页面
        @404 expression {http.error.status_code} == 404
        @50x expression {http.error.status_code} >= 500 && {http.error.status_code} < 600
        
        # 404错误处理
        handle @404 {
            rewrite * /404.html
            root * /var/www/html
            file_server
            header Content-Type "text/html; charset=utf-8"
        }
        
        # 50x错误处理
        handle @50x {
            rewrite * /50x.html
            root * /var/www/html
            file_server
            header Content-Type "text/html; charset=utf-8"
            header Cache-Control "no-cache"
        }
    }
}

2. 🔧 错误处理部分详解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
## 错误处理配置
handle_errors {
    ## 基于错误代码的路由
    @404 expression {http.error.status_code} == 404
    @500 expression {http.error.status_code} == 500
    @502 expression {http.error.status_code} == 502
    @503 expression {http.error.status_code} == 503
    @504 expression {http.error.status_code} == 504
    
    ## 通用错误处理
    rewrite * /error.html?code={http.error.status_code}
    root * /var/www/html
    file_server
    header Content-Type "text/html; charset=utf-8"
    
    ## 可以添加更多自定义头
    header X-Error "Handled by Caddy"
}

3. ⚡ 配置生效命令

1
2
3
4
5
6
7
8
9
10
# 格式化Caddy配置
sudo caddy fmt --overwrite /etc/caddy/Caddyfile

# 重新加载Caddy配置
sudo systemctl reload caddy

# 或者使用Caddy API
curl -X POST http://localhost:2019/load \
    -H "Content-Type: text/caddyfile" \
    --data-binary @/etc/caddy/Caddyfile

🎨 三、错误页面设计

1. 📝 创建错误页面文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# 创建错误页面目录
sudo mkdir -p /var/www/html

# 创建50x.html错误页面
sudo tee /var/www/html/50x.html <<'EOF'
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>服务器错误 - 500</title>
    <style>
        body { 
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            height: 100vh;
            display: flex;
            align-items: center;
            justify-content: center;
            color: white;
            text-align: center;
        }
        .error-container {
            background: rgba(255, 255, 255, 0.1);
            padding: 2rem;
            border-radius: 1rem;
            backdrop-filter: blur(10px);
        }
        h1 { font-size: 4rem; margin: 0; }
        p { font-size: 1.2rem; }
        .home-btn {
            background: white;
            color: #667eea;
            padding: 0.8rem 2rem;
            text-decoration: none;
            border-radius: 2rem;
            display: inline-block;
            margin-top: 1rem;
            transition: transform 0.3s;
        }
        .home-btn:hover {
            transform: translateY(-2px);
        }
    </style>
</head>
<body>
    <div class="error-container">
        <h1>500</h1>
        <h2>服务器内部错误</h2>
        <p>抱歉，服务器遇到了意外错误。请稍后再试。</p>
        <a href="/" class="home-btn">返回首页</a>
    </div>
</body>
</html>
EOF

2. 📱 响应式错误页面

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 创建404.html页面
sudo tee /var/www/html/404.html <<'EOF'
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>页面未找到 - 404</title>
    <style>
        /* 响应式设计 */
        @media (max-width: 768px) {
            .error-container {
                margin: 1rem;
                padding: 1rem;
            }
            h1 { font-size: 3rem; }
        }
    </style>
</head>
<body>
    <!-- 页面内容 -->
</body>
</html>
EOF

⚙️ 四、高级配置技巧

1. 🔄 基于位置的错误处理

1
2
3
4
5
6
7
8
9
10
# Nginx - 根据不同路径设置不同错误页面
location /api/ {
    error_page 500 /api/50x.html;
    proxy_pass http://backend;
}

location /static/ {
    error_page 404 /static/404.html;
    root /var/www/static;
}

2. 📊 错误日志记录

1
2
3
4
5
6
7
8
9
10
11
12
13
# Nginx错误日志配置
error_log /var/log/nginx/error.log warn;

# 在server块中添加错误日志记录
server {
    # 记录详细错误信息
    error_page 404 = @404_error;
    
    location @404_error {
        access_log /var/log/nginx/404.log;
        return 404;
    }
}

3. 🚀 性能优化配置

1
2
3
4
5
6
7
8
9
10
11
# 错误页面缓存优化
location = /50x.html {
    root /var/www/html;
    internal;
    # 适当缓存错误页面
    expires 1h;
    add_header Cache-Control "public";
    # 启用gzip压缩
    gzip on;
    gzip_types text/html;
}

🔍 五、测试与调试

1. 🧪 测试错误页面

1
2
3
4
5
6
7
8
# 测试404错误
curl -I http://localhost/nonexistent-page

# 测试500错误（模拟后端错误）
curl -X POST http://localhost/api/test-error

# 测试SSL错误
curl -k https://localhost:6663

2. 📋 调试技巧

1
2
3
4
5
6
7
8
9
10
11
12
# 查看Nginx错误日志
tail -f /var/log/nginx/error.log

# 查看Caddy日志
journalctl -u caddy -f

# 检查配置文件语法
nginx -t
caddy validate

# 测试错误页面内容
curl http://localhost/50x.html

3. 🐛 常见问题排查

1
2
3
4
5
6
7
8
9
# 检查文件权限
ls -la /var/www/html/50x.html

# 检查目录存在性
[ -d /var/www/html ] && echo "目录存在" || echo "目录不存在"

# 检查服务状态
systemctl status nginx
systemctl status caddy

⚠️ 六、注意事项

1. 🔒 安全注意事项

1
2
3
4
5
6
# 设置正确的文件权限
chmod 644 /var/www/html/50x.html
chown www-data:www-data /var/www/html/50x.html

# 防止错误页面信息泄露
# 在生产环境中避免显示详细错误信息

2. 📊 性能考虑

  • ✅ 错误页面应该轻量级，避免大量资源加载
  • ✅ 适当缓存错误页面，但不要缓存太久
  • ✅ 确保错误处理不会影响正常请求性能

3. 🎯 用户体验建议

  1. 友好的错误消息：提供清晰、友好的错误说明
  2. 导航选项：包含返回首页或联系支持的链接
  3. 品牌一致性：错误页面设计与网站风格一致
  4. 多语言支持：根据需要提供多语言错误页面

4. 🆘 紧急恢复

如果配置错误导致服务不可用：

1
2
3
4
5
6
7
8
9
# 快速恢复Nginx
sudo nginx -s stop
sudo cp /etc/nginx/nginx.conf.backup /etc/nginx/nginx.conf
sudo nginx

# 快速恢复Caddy
sudo systemctl stop caddy
sudo cp /etc/caddy/Caddyfile.backup /etc/caddy/Caddyfile
sudo systemctl start caddy

🎯 配置完成检查清单

  • [ ] Nginx/Caddy 错误页面配置完成
  • [ ] 错误页面HTML文件已创建并测试
  • [ ] 文件权限和所有权设置正确
  • [ ] 配置语法检查通过
  • [ ] 错误处理功能测试正常
  • [ ] 日志记录配置正确
  • [ ] 备份配置文件已创建

💡 提示：配置完成后建议进行全面的错误测试：

1
2
3
# 测试各种错误状态码
curl -o /dev/null -s -w "%{http_code}\n" http://localhost/nonexistent
curl -o /dev/null -s -w "%{http_code}\n" http://localhost/api/error

通过以上配置，您的网站将能够优雅地处理各种错误情况，为用户提供更好的体验！ 🚀🛡️