文档
一个 项目

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
		sort <sort_field> [<direction>]
	}
	precompressed [<formats...>]
	status        <status>
	disable_canonical_uris
	pass_thru
}

  • fs 指定要使用的替代（可能是虚拟的）文件系统。这里可以使用任何位于 caddy.fs 命名空间中的 Caddy 模块。任何根路径/前缀仍将适用于替代文件系统模块。默认情况下使用本地磁盘。

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

  • root 设置站点根路径。它类似于 root 指令，但仅适用于此 file server 实例，并覆盖可能已定义的任何其他站点根。默认：{http.vars.root} 或当前工作目录。注意：此子指令仅更改此处理程序的根。若要让其他指令（如 try_files 或 templates）也使用相同的站点根，请改用 root 指令。

  • hide 是要隐藏的文件或文件夹列表；如果被请求，文件服务器会假装它们不存在。接受占位符和通配符模式。注意这些是“文件系统”路径，而不是请求路径。换言之，相对路径使用当前工作目录作为基准，而不是站点根；并且在比较之前（如果可能）所有路径都会被转换为其绝对形式。指定没有路径分隔符的文件名或模式将隐藏所有具有匹配名称的文件，不论其位置；否则，会先尝试路径前缀匹配，然后再进行通配符匹配。由于这是一个 Caddyfile 配置，活动配置文件将默认被添加。

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

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

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

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

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

  • precompressed 是要搜索预压缩旁车（sidecar）文件的编码格式列表。参数是按顺序的编码格式列表，用于搜索预压缩的旁车文件。支持的格式有 gzip（.gz）、zstd（.zst）和 br（.br）。如果省略格式，则默认按 br zstd gzip（该顺序）。

    所有文件查找都会先查找未压缩文件是否存在。一旦找到，Caddy 会按启用格式的文件扩展名查找旁车文件。如果找到预压缩的旁车文件，Caddy 将使用该预压缩文件响应，并相应地设置 Content-Encoding 响应头。否则，Caddy 将像往常一样返回未压缩文件。如果启用了 encode 指令，并且未使用预压缩文件，则可能会在传输时对响应进行即时压缩。

  • status 是在写入响应时可选的状态码覆盖。对于使用自定义错误页面 响应请求时特别有用。可以是一个三位数的状态码，例如：404。支持占位符。默认情况下，写入的状态码通常为 200，对于部分内容为 206。

  • disable_canonical_uris 禁用默认的规范 URI 重定向行为（当请求路径为目录时添加尾部斜杠，或当请求路径为文件时移除尾部斜杠）。注意，默认情况下，如果请求路径的最后一部分（文件名）经历了内部重写，则不会进行规范化，以避免用隐式行为覆盖显式重写。

  • 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.br、/path/to/file.zst 和 /path/to/file.gz 的存在，并以对应的 Content-Encoding 提供第一个可用的文件：

file_server {
	precompressed
}