文件
由 專案提供

file_server

一個靜態檔案伺服器，支援真實和虛擬檔案系統。它通過將請求的 URI 路徑附加到站點的根路徑來形成檔案路徑。

預設情況下，它會強制執行規範 URI；這表示對於不以斜線結尾的目錄（添加斜線），或以斜線結尾的檔案（移除斜線）的請求，將發出 HTTP 重定向。但是，如果內部重寫修改了路徑的最後一個元素（檔案名稱），則不會發出重定向。

通常，file_server 指令會與 root 指令配對使用，以設定整個站點的檔案根目錄。此指令也有一個 root 子指令（見下文），用於僅為此處理器設定根目錄（不建議使用）。請注意，站點根目錄不提供沙箱保證：檔案伺服器確實可以防止從路徑組件進行目錄遍歷，但根目錄中的符號連結仍然允許存取根目錄外部的內容。

當發生錯誤時（例如，找不到檔案 404，拒絕存取 403），將調用錯誤路由。使用 handle_errors 指令來定義錯誤路由，並顯示自訂錯誤頁面。

當使用 browse 時，預設輸出由 HTML 模板產生。客戶端可以請求目錄列表為 JSON 或純文字格式，分別使用 Accept: application/json 或 Accept: text/plain 標頭。JSON 輸出對於腳本編寫很有用，而純文字輸出對於人工終端使用很有用。

語法

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

  • fs 指定要使用的替代（可能是虛擬）檔案系統。此處可以使用 caddy.fs 命名空間中的任何 Caddy 模組。任何根路徑/前綴仍然適用於替代檔案系統模組。預設情況下，使用本機磁碟。

    xcaddy v0.4.0 引入了 --embed 標誌，以將檔案系統樹嵌入到自訂 Caddy 建置中，並註冊一個名為 embedded 的 fs 模組，該模組允許您的靜態站點作為 Caddy 可執行檔分發。

  • root 設定站點根目錄的路徑。它類似於 root 指令，但它僅適用於此檔案伺服器實例，並覆蓋可能已定義的任何其他站點根目錄。預設值：{http.vars.root} 或當前工作目錄。注意：此子指令僅更改此處理器的根目錄。為了讓其他指令（例如 try_files 或 templates）知道相同的站點根目錄，請改用 root 指令。

  • hide 是要隱藏的檔案或資料夾的列表；如果被請求，檔案伺服器將假裝它們不存在。接受佔位符和 glob 模式。請注意，這些是檔案系統路徑，而不是請求路徑。換句話說，相對路徑使用當前工作目錄作為基礎，而不是站點根目錄；並且所有路徑在比較之前都會轉換為其絕對形式（如果可能）。指定不帶路徑分隔符的檔案名稱或模式將隱藏所有具有匹配名稱的檔案，無論其位置如何；否則，將嘗試路徑前綴匹配，然後是全域匹配。由於這是 Caddyfile 配置，因此預設情況下將添加活動配置檔案。

  • index 是要查找作為索引檔案的檔案名稱列表。預設值：index.html index.txt

  • browse 為沒有索引檔案的目錄請求啟用檔案列表。

    • <template_file> 是用於目錄列表的可選自訂模板檔案。預設為可以使用命令 caddy file-server export-template 提取的模板，該命令將預設模板列印到 stdout。嵌入式模板也可以在 此處的原始碼中找到 external link。瀏覽模板也可以使用 標準模板模組 中的動作。

    • reveal_symlinks 啟用在目錄列表中顯示符號連結的目標。預設情況下，符號連結目標被隱藏，僅顯示連結檔案本身。

    • sort 更改目錄列表的預設排序。第一個參數是要排序的欄位/列：name、namedirfirst、size 或 time。第二個參數是可選方向：asc 或 desc。例如，sort name desc 將按名稱降序排序。

  • precompressed 是用於搜尋預先壓縮的 sidecar 檔案的編碼格式列表。參數是要搜尋預先壓縮的 sidecar 檔案的編碼格式的排序列表。支援的格式為 gzip (.gz)、zstd (.zst) 和 br (.br)。如果省略格式，則預設為 br zstd gzip（按此順序）。

    所有檔案查找將首先查找未壓縮檔案的存在。找到後，Caddy 將查找具有每個啟用格式的檔案擴展名的 sidecar 檔案。如果找到預先壓縮的 sidecar 檔案，Caddy 將使用預先壓縮的檔案進行回應，並適當地設定 Content-Encoding 回應標頭。否則，Caddy 將像往常一樣使用未壓縮的檔案進行回應。如果啟用了 encode 指令，則如果未預先壓縮，它可能會即時壓縮回應。

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

  • disable_canonical_uris 禁用重定向的預設行為（如果請求路徑是目錄，則添加尾部斜線，如果請求路徑是檔案，則移除尾部斜線）。請注意，預設情況下，如果請求路徑的最後一個元素（檔案名稱）經過內部重寫，則不會進行規範化，以避免用隱式行為破壞顯式重寫。

  • pass_thru 啟用 pass-thru 模式，如果找不到請求的檔案，則繼續路由中的下一個 HTTP 處理器，而不是觸發 404 錯誤（調用 handle_errors 路由）。實際上，這僅在 route 區塊中使用 file_server 後面跟著其他處理器指令時才有用，因為此指令實際上是 最後排序的。

範例

當前目錄中的靜態檔案伺服器

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.br、/path/to/file.zst 和 /path/to/file.gz，並服務第一個可用的檔案，並帶有相應的 Content-Encoding

file_server {
	precompressed
}