# 自定义错误页面

Source: https://support.kapsulehost.com/zh-cn/site-error-pages

自定义错误页面可以用您自己的品牌HTML替换服务器默认的简陋页面，同时保留真实的错误状态，让搜索引擎仍然能看到真正的404。本指南将介绍如何为每个受支持的代码添加页面、出于安全考虑会被剥离的内容，以及验证徽章的工作原理。

## 错误页面在KPanel中的位置

1. 登录到[KPanel](https://kpanel.kapsulehost.com)。
2. 点击左侧边栏中的**网站**，然后点击该站点。
3. 在站点的左侧菜单中，打开**设置**，然后点击**错误页面**。

直接访问地址是`/websites/<site-id>/error-pages`。

![KPanel中某站点的自定义错误页面](https://support.kapsulehost.com/help/screenshots/site-error-pages.89c17e2d.webp)

## 为什么要费心设置

默认的服务器错误页面是一条死胡同。它没有品牌标识，没有导航，也没有任何说明，因此访问者一旦碰到它，通常就会直接离开。

自定义页面则能将其转化为引导访客重新回到站点的入口：您的徽标、您的排版风格、一句用您自己的语气写的话，以及一个返回首页或搜索框的链接。对于大型站点来说，拼写错误和过时的URL会持续产生一定的流量，而404页面是您能够建立的最廉价的挽回手段。

## 支持的代码

您可以为八种代码分别设置一个自定义页面，每种代码对应一个页面：

| 代码 | 含义 | 常见原因 |
|---|---|---|
| 400 | 请求错误 | 请求格式错误 |
| 401 | 未授权 | 需要身份验证或验证失败 |
| 403 | 禁止访问 | 访问规则阻止了该请求 |
| 404 | 未找到 | 该URL不存在任何内容 |
| 500 | 内部服务器错误 | 您的应用程序出现故障 |
| 502 | 网关错误 | 应用程序未正确响应 |
| 503 | 服务不可用 | 应用程序已宕机或负载过高 |
| 504 | 网关超时 | 应用程序响应时间过长 |

请先从404开始设置。它是迄今为止最常见的情况，也是访问者在正常浏览中会遇到的，而非故障导致的唯一一种。

接下来值得处理的是5xx系列，因为这些页面是人们在您最糟糕的一天看到的页面。一个冷静、有品牌感的页面，说明出了点问题并提供一个联系邮箱，要比一个空白的服务器错误页面好得多。

## 添加一个页面

1. 点击**添加错误页面**。
2. 从下拉菜单中选择一个错误代码。已使用的代码不会出现在列表中。
3. 将**HTML 正文**字段中的示例HTML替换为您自己的内容。
4. 点击**添加错误页面**。

编辑器会以一个可用的404文档作为起点，供您在此基础上进行编辑删减，如果您只是想快速得到一个整洁的页面，这是一个合理的起点。

## 编写HTML

请提供一份完整的HTML文档，以文档类型声明开头。该页面会按原样提供，因此必须能够独立运行。

出于安全考虑，部分HTML会在页面被存储之前被剥离：

- `<script>` 标签
- 诸如`onclick`之类的内联事件处理程序
- iframe
- 远程样式表

如果有任何内容被移除，保存后系统会提示警告信息。

> **Warning:** 由于远程样式表会被剥离，错误页面无法引入您站点的主CSS文件。请使用内联CSS或文档头部的`<style>`块来设置样式。这是刻意设计的：错误页面必须在网站其余部分出现故障时依然能够正常渲染，而一个依赖于从出故障的服务器获取资源的页面，恰恰会在最不合时宜的时刻呈现为无样式的文本。

实用建议：

- **让页面保持精简且自成一体。** 将所有内容内联化。避免使用外部图片。页面列表会显示每个页面以KB为单位的大小。
- **用通俗的语言说明发生了什么。** “我们找不到该页面”要比“404 Not Found”更好。
- **提供一条出路。** 一个返回首页的链接、指向主要板块的链接，或一个搜索框。
- **在5xx页面上包含联系方式**，因为访问者此时无法通过网站本身联系到您。
- **不要用它来做重定向。** 如果某个URL已经迁移，请正确设置重定向，而不要用这种方式。请参阅[站点重定向](https://support.kapsulehost.com/zh-cn/site-redirects)。

## 状态代码会被保留

您的自定义页面会以真实的错误状态提供，而不是200。一个404自始至终对客户端都保持为404。

这一点比听起来更重要。如果品牌页面以200状态返回，那就是一种“软404”：搜索引擎会将其作为真正的页面进行索引，您的分析工具会将其计为一次成功的访问，任何工具也都不会标记出失效链接。由于KapsuleHost保留了真实状态，上述所有机制都能继续正常工作。

## 解读状态徽章

**状态**列报告的是实际能够被验证的内容，并且在限制方面刻意保持诚实。

| 徽章 | 含义 |
|---|---|
| 已验证：品牌页面已提供（真实404） | 我们从外部强制触发了一次404，并获得了带有正确状态的您的页面 |
| 已配置（未进行外部测试） | 该页面已应用。该代码无法按需从外部触发 |
| 尚未验证 | 检查尚未运行 |
| 已应用，现场测试结果不确定 | 探测得到的并非干净的404响应，通常是因为被重定向拦截了 |
| 获得了404但未提供品牌页面 | 规则已生效，但您的页面未被返回。请尝试重新保存 |

只有404可以从外部强制触发。请求一个不存在的URL可以可靠地产生404，但没有办法在不破坏服务器正常运行的情况下，按需让一个健康的服务器产生真正的500错误。因此，其他代码报告为**已配置**，而不会声称进行了一次从未真正发生的验证。当错误真正发生时，它们仍然会正常提供服务。

您也可能会看到一条警告，提示服务器上的另一个配置声明使用了相同的域名。在该问题解决之前，错误页面可能无法生效。如果您看到此提示，请联系支持团队。

## 排查实际正在出错的站点

如果您来到这里是因为您的站点正在报错，而不是想要更美观的页面，那么本页面提供了一个快捷方式：页面顶部横幅中的**使用Kora排查问题**按钮。

它会请求KPanel内置的助手Kora读取该站点的错误日志和近期故障记录，并告诉您可能的原因及修复方法。这比直接查看原始日志要快得多，是更理想的第一步。

关于底层的性能状况，请参阅[站点性能与APM](https://support.kapsulehost.com/zh-cn/site-performance)；关于一段时间内的错误率，请参阅[站点流量分析](https://support.kapsulehost.com/zh-cn/site-analytics)。

## 编辑和删除

每一行都有一个编辑按钮，点击后会打开同一个编辑器，其中代码已固定，HTML内容已加载；此外还有一个删除按钮。

删除操作会要求确认，并说明结果：命中该代码的请求将回退到服务器默认页面。

## 故障排查

**我的页面没有显示出来。** 请确认您触发的是正确的代码。重定向的路径永远不会到达404状态。请使用一个确实不存在的URL进行测试，并在隐私浏览窗口中进行，以排除缓存的影响。

**页面显示了，但看起来没有样式。** 您的样式表作为远程资源被剥离了。请将CSS内联。

**我的跟踪脚本不见了。** 脚本会被设计性地剥离。目前没有办法在自定义错误页面中运行JavaScript。

**所有代码都已经有页面了。** 八种代码都已被使用。请编辑现有页面，而不是再添加新页面。

**徽章显示品牌页面未被提供。** 请重新保存该页面。如果问题仍然存在，并且没有出现域名冲突警告，请提交工单。

## 相关页面

- [站点重定向](https://support.kapsulehost.com/zh-cn/site-redirects)，可从源头上避免发生404。
- [站点流量分析](https://support.kapsulehost.com/zh-cn/site-analytics)，查看您的站点实际提供了多少4xx和5xx响应。
- [为站点设置密码保护](https://support.kapsulehost.com/zh-cn/site-password-protect)，该功能会按设计产生401响应。