创建自定义错误规则

在仪表板中

创建自定义错误规则

在 Cloudflare 仪表板中，前往 Rules Overview（概览） 页面。
Go to Overview ↗
选择 Create rule（创建规则） > Custom Error Rule（自定义错误规则）。
在 Rule name（规则名称） 中为规则输入描述性名称。
在 If incoming requests match（如果传入请求匹配） 下，选择以下选项之一：
- Custom filter expression（自定义过滤表达式）：规则仅应用于匹配自定义表达式的流量。定义规则表达式以配置应重写哪些请求。使用 Expression Builder 或 Expression Editor 定义自定义表达式。更多信息请参阅在仪表板中编辑表达式。
- All incoming requests（所有传入请求）：规则将应用于状态代码为 400 及以上的所有响应，Cloudflare 安全产品发出的 block 与 challenge 操作除外。
在 Deliver a custom error response（交付自定义错误响应） 中，选择响应类型（Custom error asset 或可用的内联响应之一）。

若选择 Custom error asset，请在 Asset（资源） 中选择现有自定义错误资源，或选择 Create new asset（创建新资源） 以创建新的自定义错误资源。

若选择 JSON response、HTML response、Text response 或 XML response，请分别在 JSON response、HTML response、Text response 或 XML response 中输入要发送给网站访客的自定义错误响应。响应可包含 error tokens，Cloudflare 会在将响应发送给访客前将其替换为实际值。最大响应大小为 10 KB。
（可选）在 Response code（响应代码） 中输入响应的 HTTP 状态代码（介于 400 与 999 之间的整数值）。若提供，此值将覆盖当前响应状态代码。
（可选）在 Place at（放置位置） 下，定义规则在规则列表中的位置：列表中的第一条规则、最后一条规则，或自定义位置（在给定规则之后）。
要保存并部署规则，选择 Deploy（部署）。若尚未准备好部署规则，选择 Save as Draft（保存为草稿）。

创建自定义错误资源

在 Create Custom Error Asset（创建自定义错误资源） 侧边栏中，在 Asset name（资源名称） 中输入资源名称。
（可选）在 Description（描述） 中输入资源描述。
在 URL（网址） 中，输入你希望获取并存储在 Cloudflare 全球网络中的页面 URL。Cloudflare 将获取所有页面资源，并存储你可在一条或多条自定义错误规则中使用的页面精简版本。
选择 Save（保存）。

要查看现有自定义错误资源，请前往 Rules（规则） > Settings（设置） > Custom Error Assets（自定义错误资源） 选项卡。

通过 API

要通过 API 配置自定义错误规则：

（可选）基于你提供的 URL 创建自定义错误资源。
使用 Rulesets API 在 http_custom_errors 阶段创建自定义错误规则。

创建自定义错误资源

以下 POST 请求基于提供的 URL 在 zone 中创建新的自定义错误资源：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets" \
--header "Authorization: Bearer <API_TOKEN>" \
--json '{
  "name": "500_error_template",
  "description": "Standard 5xx error template page",
  "url": "https://example.com/errors/500_template.html"
}'

{
	"result": {
		"name": "500_error_template",
		"description": "Standard 5xx error template page",
		"url": "https://example.com/errors/500_template.html",
		"last_updated": "2025-02-10T11:36:07.810215Z",
		"size_bytes": 2048
	},
	"success": true
}

创建自定义错误规则

通过 API 创建自定义错误规则时，请确保：

将规则操作设为 serve_error。
根据响应类型在 action_parameters 字段中定义规则参数。
将规则部署到 http_custom_errors 阶段。

http_custom_errors 阶段 ruleset 中第一条匹配的规则将被应用。ruleset 中的其他规则将不会被匹配或应用。此外，在 zone 级别定义的自定义错误规则优先于在账户级别定义的规则。

一般流程

按此工作流通过 API 为给定 zone 创建自定义错误规则：

使用 List zone rulesets 操作检查 zone 级别是否已有 http_custom_errors 阶段的 ruleset。
若阶段 ruleset 不存在，请使用 Update a zone entry point ruleset 操作创建它，该操作允许你在 ruleset 不存在时创建它，并更新 ruleset 中的所有规则。在 http_custom_errors 阶段创建 ruleset。

若阶段 ruleset 已存在，请使用 Update a zone entry point ruleset 操作替换 ruleset 中的所有规则，或使用 Add a rule to a ruleset 操作向 ruleset 中的现有规则添加规则。

要在账户级别创建自定义错误规则，请使用相应的账户级 API 端点。

示例

此示例配置一条自定义错误规则，对 HTTP 状态代码为 500 的响应返回先前创建的自定义错误资源 500_error_template。

Required API token permissions

At least one of the following token permissions is required:

Response Compression Write
Config Settings Write
Dynamic URL Redirects Write
Cache Settings Write
Custom Errors Write
Origin Write
Managed headers Write
Zone Transform Rules Write
Mass URL Redirects Write
Magic Firewall Write
L4 DDoS Managed Ruleset Write
HTTP DDoS Managed Ruleset Write
Sanitize Write
Transform Rules Write
Select Configuration Write
Bot Management Write
Zone WAF Write
Account WAF Write
Account Rulesets Write
Logs Write
Logs Write

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_custom_errors/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"ref": "serve_500_template",
						"action": "serve_error",
						"action_parameters": {
								"asset_name": "500_error_template",
								"content_type": "text/html"
						},
						"expression": "http.response.code eq 500",
						"enabled": true
				}
		]
	}'

使用 Terraform 时，通过 ref 字段可在更新后保持稳定的规则 ID。添加该字段可防止 Terraform 在变更时重建规则。更多信息请参阅故障排除（Terraform 文档）。

此 PUT 请求对应 Update a zone entry point ruleset 操作，会替换 http_custom_errors 阶段入口点 ruleset 中的任何现有规则。

所需的 API token 权限

用于管理 Custom Error Rules 与 Custom Error Assets 的 API 请求中的 API token 必须至少具有以下权限：

Custom Error Rules > Edit