file_server

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

默认情况下，它会强制执行规范URI；这意味着对于不以尾部斜线结尾的目录请求，会发出HTTP重定向来添加尾部斜线；对于带有尾部斜线的文件请求，会发出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
		sort <sort_field> [<direction>]
		file_limit <number>
	}
	precompressed [<formats...>]
	status        <status>
	disable_canonical_uris
	pass_thru
}

• fs 指定要使用的备用（也许是虚拟的）文件系统。可以使用caddy.fs命名空间中的任何Caddy模块。任何根路径/前缀仍会应用到备用文件系统模块。默认情况下使用本地磁盘。

  xcaddy v0.4.0引入了--embed标志，可将文件系统树嵌入到自定义Caddy构建中，并注册名为embedded的fs模块，让你的静态站点可以作为Caddy可执行文件分发。

• root 设置站点根路径。它类似于root指令，但只应用于这个文件服务器实例，并会覆盖任何可能已经定义的其他站点根。默认值：{http.vars.root}或当前工作目录。注意：这个子指令只改变此处理器的根目录。对于其他指令（例如try_files或templates），如果需要知道相同的站点根目录，应使用root指令。

• hide 是要隐藏的文件或文件夹列表；如果请求这些文件，文件服务器会假装它们不存在。它接受占位符和glob模式。注意，这些是 文件系统 路径，不是请求路径。换句话说，相对路径以当前工作目录为基准，而不是站点根目录；并且所有路径在比较前都会尽可能转换为绝对形式。指定不带路径分隔符的文件名或模式时，会隐藏任何位置中所有名称匹配的文件；否则，会先尝试路径前缀匹配，然后再尝试glob匹配。由于这是Caddyfile配置，默认会加入活动配置文件。隐藏比较区分大小写；在大小写不敏感的文件系统上，大小写不同的请求路径仍可能解析到同一个磁盘路径，因此不应把hide视为保护敏感路径的安全边界。

• index 是要查找作为索引文件的文件名列表。默认值：index.html index.txt

• browse 对没有索引文件的目录请求启用文件列表。

  • <template_file> 是可选的自定义模板文件，用于目录列表。默认模板可通过caddy file-server export-template命令导出，该命令会将默认模板打印到标准输出。嵌入模板也可以在源代码中找到。目录列表模板也可以使用标准templates模块中的动作。

  • reveal_symlinks 在目录列表中显示符号链接的目标。默认情况下，符号链接目标会被隐藏，只显示链接文件本身。

  • sort 更改目录列表的默认排序。第一个参数是排序字段/列：name、namedirfirst、size或time。第二个参数是可选方向：asc或desc。例如，sort name desc会按名称降序排序。

  • file_limit 设置目录列表中最多显示的文件数。默认值：10000。如果文件数量超过此限制，只会显示前N个文件，其中N是指定的限制值。

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