file_server

一个支持真实和虚拟文件系统的静态文件服务器。它通过将请求的 URI 路径附加到站点的根路径来形成文件路径。

默认情况下，它强制规范 URI；即对不以斜杠结尾的目录请求（添加斜杠）或对以斜杠结尾的文件请求（移除斜杠）会发出 HTTP 重定向。但如果内部重写修改了路径的最后一个元素（文件名），则不会发出重定向。

通常，file_server 指令与 root 指令配对，以设置整个站点的文件根目录。该指令还有一个 root 子指令（见下文），仅为此处理器设置根目录（不推荐）。请注意，站点根目录不提供沙盒保证：文件服务器确实会阻止路径组件中的目录遍历，但根目录内的符号链接仍可能允许访问根目录之外的内容。

当发生错误时（例如文件未找到 404、权限被拒绝 403），将调用错误路由。使用 handle_errors 指令定义错误路由，并显示自定义错误页面。

使用 browse 时，默认输出由 HTML 模板生成。客户端可以通过使用 Accept: application/json 或 Accept: text/plain 头分别请求目录列表为 JSON 或纯文本。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 是要隐藏的文件或文件夹列表；如果请求这些文件，文件服务器将假装它们不存在。接受占位符和通配符模式。请注意，这些是_文件系统_路径，而不是请求路径。换句话说，相对路径使用当前工作目录作为基础，而不是站点根目录；所有路径在比较前都会转换为绝对形式（如果可能）。指定不带路径分隔符的文件名或模式将隐藏所有具有匹配名称的文件，无论其位置如何；否则，将尝试路径前缀匹配，然后进行通配符匹配。由于这是 Caddyfile 配置，默认情况下会添加活动配置文件。
index 是要查找的索引文件名列表。默认值：index.html index.txt
browse 启用对没有索引文件的目录请求的文件列表。
- <template_file> 是用于目录列表的可选自定义模板文件。默认为可使用命令 caddy file-server export-template 提取的模板，该命令将默认模板打印到标准输出。嵌入的模板也可以在源代码中找到。浏览模板可以使用标准模板模块的操作。
- reveal_symlinks 启用显示目录列表中符号链接的目标。默认情况下，符号链接目标被隐藏，仅显示链接文件本身。
- sort 更改目录列表的默认排序。第一个参数是要排序的字段/列：name、namedirfirst、size 或 time。第二个参数是可选方向：asc 或 desc。例如，sort name desc 将按名称降序排序。
precompressed 是要搜索预压缩侧边文件的编码格式列表。参数是搜索预压缩侧边文件的编码格式的有序列表。支持的格式有 gzip (.gz)、zstd (.zst) 和 br (.br)。如果省略格式，则默认为 br zstd gzip（按此顺序）。

所有文件查找都会首先查找未压缩文件的存在。一旦找到，Caddy 将查找具有每个启用格式文件扩展名的侧边文件。如果找到预压缩的侧边文件，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
}