handle_errors

设置错误处理程序。

当正常的HTTP请求处理程序返回错误时，正常处理会停止，错误处理程序会被调用。错误处理程序形成一条路由，就像普通路由一样，它们可以做普通路由能做的任何事情。这让你在处理HTTP请求期间发生的错误时有很大的控制力和灵活性。例如，你可以提供静态错误页面、模板化错误页面，或者反向代理到另一个后端来处理错误。

该指令可以使用不同状态码重复多次，以便用不同方式处理不同错误。如果未指定状态码，则匹配任何错误；如果其他错误处理程序都不匹配，它会作为后备处理程序。

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

请注意，某些指令（例如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 {
		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"
	}
}