handle_errors

设置错误处理程序。

当正常的 HTTP 请求处理程序返回错误时，正常处理停止，并调用错误处理程序。错误处理程序形成一个路由，它就像正常的路由一样，并且可以执行正常路由可以执行的任何操作。这在处理 HTTP 请求期间的错误时，实现了极大的控制和灵活性。例如，您可以提供静态错误页面、模板化错误页面，或反向代理到另一个后端来处理错误。

该指令可以重复使用不同的状态代码，以便以不同的方式处理不同的错误。如果未指定状态代码，则它将匹配任何错误，充当在任何其他错误处理程序都不匹配情况下的后备。

请求的上下文会被带入错误路由，因此在请求上下文中设置的任何值（如 站点根目录 或 变量）也会在错误处理程序中保留。此外，在处理错误时，可以使用新的占位符。

请注意，某些指令，例如 reverse_proxy，它可能会写入一个 HTTP 状态码被归类为错误的响应，不会触发错误路由。

您可以使用 error 指令根据您自己的路由决策显式触发错误。

语法

handle_errors [<status_codes...>] {
	<directives...>
}

• <status_codes...> 是一个或多个 HTTP 状态代码，用于匹配正在处理的错误。状态代码可以是 3 位数字，也可以是 4xx 或 5xx 的特殊情况，它们分别匹配 400-499 或 500-599 范围内的所有状态代码。如果未指定状态代码，则它将匹配任何错误，充当在任何其他错误处理程序都不匹配情况下的后备。

• <directives...> 是 HTTP 处理程序指令和匹配器的列表，每行一个。

占位符

在处理错误时，可以使用以下占位符。它们是 Caddyfile 简写，用于完整的占位符，可以在 HTTP 服务器错误路由的 JSON 文档中找到。

示例

基于状态代码的自定义错误页面（例如，404 错误的名为 404.html 的页面）。请注意，file_server 在 handle_errors 中运行时会保留错误的 HTTP 状态代码（假设您事先在站点中设置了 站点根目录）

handle_errors {
	rewrite * /{err.status_code}.html
	file_server
}

一个使用 templates 编写自定义错误消息的单个错误页面

handle_errors {
	rewrite * /error.html
	templates
	file_server
}

如果您只想为某些错误代码提供自定义错误页面，您可以使用 file 匹配器预先检查自定义错误文件的存在性

handle_errors {
	@custom_err file /err-{err.status_code}.html /err.html
	handle @custom_err {
		rewrite * {file_match.relative}
		file_server
	}
	respond "{err.status_code} {err.status_text}"
}

反向代理到专业服务器，该服务器非常适合处理 HTTP 错误并改善您的一天 😸

handle_errors {
	rewrite * /{err.status_code}
	reverse_proxy https://http.cat {
		header_up Host {upstream_hostport}
		replace_status {err.status_code}
	}
}

只需使用 respond 返回错误代码和名称

handle_errors {
	respond "{err.status_code} {err.status_text}"
}

以不同的方式处理特定的错误代码

handle_errors 404 410 {
	respond "It's a 404 or 410 error!"
}

handle_errors 5xx {
	respond "It's a 5xx error."
}

handle_errors {
	respond "It's another error"
}

上面的行为与下面相同，下面使用了针对状态代码的 expression 匹配器，并使用 handle 来实现互斥

handle_errors {
	@404-410 `{err.status_code} in [404, 410]`
	handle @404-410 {
		respond "It's a 404 or 410 error!"
	}

	@5xx `{err.status_code} >= 500 && {err.status_code} < 600`
	handle @5xx {
		respond "It's a 5xx error."
	}

	handle {
		respond "It's another error"
	}
}