文档
一个 项目

file_server

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

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

最常见的是，file_server 指令与 root 指令配对，以设置整个站点的文件根目录。此指令还具有一个 root 子指令（见下文），用于仅为此处理程序设置根目录（不推荐）。请注意，站点根目录不包含沙箱保证：文件服务器确实可以防止路径组件中的目录遍历，但根目录内的符号链接仍然可以允许访问根目录之外的目录。

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

语法

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

  • fs 指定要使用的备用（可能是虚拟）文件系统。caddy.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 提取的模板，该命令将默认模板打印到标准输出。嵌入式模板也可以在 源代码中找到 external link。浏览模板也可以使用来自 标准模板模块 的操作。

  • precompressed 是要搜索预压缩侧车文件的编码格式列表。参数是有序的编码格式列表，用于搜索预压缩的 侧车文件。支持的格式为 gzip (.gz)、zstd (.zst) 和 br (.br)。

    所有文件查找将首先查找未压缩文件的是否存在。找到后，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.zst、/path/to/file.br 和 /path/to/file.gz，并使用第一个可用文件以及相应的 Content-Encoding 进行响应

file_server {
	precompressed zstd br gzip
}