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"
	}
}