文件
a 專案

file_server

支援實體和虛擬檔案系統的靜態檔案伺服器。它會將要求的 URI 路徑附加到 網站根路徑 來形成檔案路徑。

預設情況下，它會強制使用正規 URI；表示會對未以斜線結尾的目錄要求 (以新增斜線) 或有斜線結尾的檔案要求 (以移除斜線) 發出 HTTP 重新導向。不過，如果內部重寫修改路徑的最後一個元素 (檔案名稱)，則不會發出重新導向。

file_server 指令最常與 root 指令配對使用，以設定整個網站的檔案根目錄。此指令也有 root 子指令 (請見下方) 來只為這個處理常式設定根目錄 (不建議使用)。請注意，網站根目錄不提供沙盒保證：檔案伺服器確實會防止路徑組件進行目錄穿越，但根目錄內的符號連結仍可能允許存取根目錄以外的內容。

發生錯誤時 (例如檔案未找到 404、拒絕存取權限 403)，將會呼叫錯誤路由。使用 handle_errors 指令來定義錯誤路由，並顯示自訂錯誤頁面。

語法

file_server [<matcher>] [browse] {
	fs            <backend...>
	root          <path>
	hide          <files...>
	index         <filenames...>
	browse        [<template_file>]
	precompressed <formats...>
	status        <status>
	disable_canonical_uris
	pass_thru
}

  • fs 指定要使用的替代 (可能是虛擬的) 檔案系統。caddy.fs 名稱空間中的任何 Caddy 模組都可以在這裡使用。任何根路徑/字首仍會套用於替代檔案系統模組。預設情況下，會使用本機磁碟。

  • root 設定網站根目錄的路徑。它類似於 root 指令，但只套用於這個檔案伺服器執行個體，並會覆寫可能已定義的任何其他網站根目錄。預設值：{http.vars.root} 或目前的作業目錄。注意：此子指令只會變更這個處理常式的根目錄。若要讓其他指令 (例如 try_files 或 templates) 知道相同的網站根目錄，請改用 root 指令。

  • hide 是檔案或資料夾的清單，用於隱藏；如果要求，檔案伺服器會假裝它們不存在。接受佔位符和 glob 模式。請注意，這些是檔案系統路徑，不是要求路徑。換句話說，相對路徑使用目前的工作目錄作為基礎，而不是網站根目錄；所有路徑在比較之前都會轉換為絕對形式（如果可能）。指定沒有路徑分隔符的檔案名稱或模式，將隱藏所有具有相符名稱的檔案，而不管其位置；否則，將嘗試路徑前綴比對，然後再進行 glob 比對。由於這是 Caddyfile 設定，因此預設會新增目前設定的檔案。

  • index 是作為索引檔案尋找的檔案名稱清單。預設：index.html index.txt

  • browse 為沒有索引檔案的目錄要求啟用檔案清單。

    • <template_file> 是目錄清單使用的自訂範本檔案（選用）。預設為可以使用指令 caddy file-server export-template 萃取的範本，它會將預設範本列印到 stdout。嵌入式範本也可以在 原始碼中找到 external link。瀏覽範本也可以使用 標準範本模組 的動作。

  • precompressed 是編碼格式的清單，用於搜尋預先壓縮的 sidecar 檔案。引數是編碼格式的有序清單，用於搜尋預先壓縮的 sidecar 檔案。支援的格式為 gzip (.gz)、zstd (.zst) 和 br (.br)。

    所有檔案查詢都會先尋找未壓縮檔案的存在。找到後，Caddy 會尋找具有每個已啟用格式的檔案副檔名的 sidecar 檔案。如果找到預先壓縮的 sidecar 檔案，Caddy 會回應預先壓縮的檔案，並適當地設定 Content-Encoding 回應標頭。否則，Caddy 會正常回應未壓縮的檔案。如果 encode 指令 已啟用，則如果未預先壓縮，它可能會即時壓縮回應。

  • status 是寫入回應時使用的狀態碼覆寫（選用）。特別適用於使用 自訂錯誤頁面 回應要求。可以是 3 位數的狀態碼，例如：404。支援佔位符。預設情況下，寫入的狀態碼通常會是 200，或部分內容的 206。

  • disable_canonical_uris 停用預設的重新導向行為（如果請求路徑是目錄，則新增尾斜線；如果請求路徑是檔案，則移除尾斜線）。請注意，預設情況下，如果請求路徑的最後一個元素（檔案名稱）經過內部重寫，則不會進行正規化，以避免用隱含行為覆蓋明確的重寫。

  • pass_thru 啟用直通模式，如果找不到請求的檔案，則繼續執行路由中的下一個 HTTP 處理常式，而不是觸發 404 錯誤（呼叫 handle_errors 路由）。實際上，這僅在包含其他處理常式指令（在 file_server 之後）的 route 區塊中才有用，因為此指令實際上是 最後排序的。

範例

從目前目錄中提供靜態檔案伺服器

file_server

啟用檔案清單

file_server browse

僅在 /static 資料夾中提供靜態檔案

file_server /static/*

file_server 指令通常與 root 指令 配對，以設定提供檔案的根路徑

example.com {
	root * /srv
	file_server
}

隱藏所有 .git 資料夾及其內容

file_server {
	hide .git
}

如果客戶端支援（Accept-Encoding 標頭），則會檢查請求的檔案旁是否存在預先壓縮的檔案。因此，如果請求 /path/to/file，則會依序檢查 /path/to/file.zst、/path/to/file.br 和 /path/to/file.gz，並提供第一個可用的檔案，並提供對應的內容編碼

file_server {
	precompressed zstd br gzip
}