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。嵌入式模板也可以在此处在源代码中找到。浏览模板也可以使用来自标准模板模块的操作。
- 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 启用传递模式，如果未找到请求的文件，则继续路由中的下一个 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
}