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 简写。

示例

基于状态码的自定义错误页面（即对于 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"
	}
}