Skip to main content
Version: 3.17

error-page

描述#

error-page 插件允许自定义 APISIX 本身生成的 HTTP 错误响应（例如，路由不匹配或上游不可达时）的响应体和内容类型。来自上游服务的响应不会受到影响。

该插件通过插件元数据进行全局配置，无需在路由上配置属性。启用后，它会拦截错误响应并将响应体替换为配置的自定义内容。

插件元数据#

该插件不支持在路由、服务或其他资源上配置属性，所有配置均通过插件元数据完成。

名称类型必选项默认值描述
enableboolean否false设为 true 以启用插件。
error_404object否404 响应的自定义错误页面配置。
error_404.bodystring否默认 HTML 页面404 响应的响应体内容。
error_404.content_typestring否text/html响应体的内容类型。
error_500object否500 响应的自定义错误页面配置。
error_500.bodystring否默认 HTML 页面500 响应的响应体内容。
error_500.content_typestring否text/html响应体的内容类型。
error_502object否502 响应的自定义错误页面配置。
error_502.bodystring否默认 HTML 页面502 响应的响应体内容。
error_502.content_typestring否text/html响应体的内容类型。
error_503object否503 响应的自定义错误页面配置。
error_503.bodystring否默认 HTML 页面503 响应的响应体内容。
error_503.content_typestring否text/html响应体的内容类型。

启用插件#

error-page 插件默认禁用。要启用该插件，请将其添加到配置文件（conf/config.yaml）中：

conf/config.yaml
plugins:
  - ...
  - error-page

配置插件元数据#

note

你可以通过以下命令从 config.yaml 中获取 admin_key 并保存为环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

配置插件元数据，启用插件并定义自定义错误页面：

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "enable": true,
    "error_404": {
        "body": "<html><body><h1>404 - 页面未找到</h1></body></html>",
        "content_type": "text/html"
    },
    "error_500": {
        "body": "<html><body><h1>500 - 服务器内部错误</h1></body></html>",
        "content_type": "text/html"
    },
    "error_502": {
        "body": "<html><body><h1>502 - 网关错误</h1></body></html>",
        "content_type": "text/html"
    },
    "error_503": {
        "body": "<html><body><h1>503 - 服务不可用</h1></body></html>",
        "content_type": "text/html"
    }
}'

你也可以通过设置自定义 content_type 来返回 JSON 格式的错误响应：

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "enable": true,
    "error_404": {
        "body": "{\"code\": 404, \"message\": \"资源未找到\"}",
        "content_type": "application/json"
    },
    "error_500": {
        "body": "{\"code\": 500, \"message\": \"服务器内部错误\"}",
        "content_type": "application/json"
    }
}'

由于该插件使用全局元数据，你还需要在路由上启用该插件。可以使用全局规则将其应用于所有路由：

curl http://127.0.0.1:9180/apisix/admin/global_rules/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "error-page": {}
    }
}'

示例#

按照上述方式配置插件和元数据后，访问一个不存在的路由触发 404 错误：

curl -i http://127.0.0.1:9080/non-existent-path
HTTP/1.1 404 Not Found
Content-Type: text/html
...

<html><body><h1>404 - 页面未找到</h1></body></html>

禁用插件#

若要停止插件拦截错误响应，删除插件元数据：

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page \
-H "X-API-KEY: $admin_key" -X DELETE

若要从路由中完全移除该插件，删除路由插件配置中对应的 JSON 配置。APISIX 将自动重新加载，无需重启。

curl http://127.0.0.1:9180/apisix/admin/global_rules/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {}
}'