文档
一个 项目

Caddyfile 指令

指令是出现在站点块内的功能性关键字。有时它们可以打开自己的块，包含_子指令_，但除非特别说明，指令不能嵌套在其他指令内。例如，不能在 file_server 块内用 basic_auth，因为 file_server 不支持认证。但你可以在 handle 和 route 等特殊指令块内使用某些指令，因为它们专为分组 HTTP 处理器指令设计。

以下指令是 Caddy 标准自带的，可在 HTTP Caddyfile 中使用：

指令 描述
abort 终止 HTTP 请求
acme_server 内嵌 ACME 服务器
basic_auth 强制 HTTP 基本认证
bind 自定义服务器套接字地址
encode 编码（通常压缩）响应
error 触发错误
file_server 从磁盘服务文件
forward_auth 委托认证给外部服务
fs 设置用于文件 I/O 的文件系统
handle 互斥指令组
handle_errors 定义错误处理路由
handle_path 类似 handle，但会去除路径前缀
header 设置或移除响应头
import 包含片段或文件
intercept 拦截其他处理器写入的响应
invoke 调用命名路由
log 启用访问/请求日志
log_append 向访问日志追加字段
log_skip 跳过匹配请求的访问日志
log_name 覆盖要写入的日志器名称
map 将输入值映射到一个或多个输出
method 内部更改 HTTP 方法
metrics 配置 Prometheus 指标暴露端点
php_fastcgi 通过 FastCGI 服务 PHP 站点
push 使用 HTTP/2 服务器推送内容到客户端
redir 向客户端发出 HTTP 重定向
request_body 操作请求体
request_header 操作请求头
respond 向客户端写入硬编码响应
reverse_proxy 强大且可扩展的反向代理
rewrite 内部重写请求
root 设置站点根路径
route 一组被视为单元的指令
templates 对响应执行模板
tls 自定义 TLS 设置
tracing 集成 OpenTelemetry 链路追踪
try_files 依赖文件存在性的重写
uri 操作 URI
vars 设置任意变量

语法

每个指令的语法大致如下：

directive [<matcher>] <args...> {
	subdirective [<args...>]
}

<尖括号> 表示需替换为实际值。

[方括号] 表示可选参数。

省略号 ... 表示可继续，即一个或多个参数或行。

子指令通常是可选的，除非另有说明，即使它们未出现在 [方括号] 中。

匹配器

大多数（但不是全部）指令接受匹配器 token，用于过滤请求。匹配器 token 通常是可选的。指令支持匹配器时，其语法如下：

[<matcher>]

由于所有匹配器 token 工作方式相同，具体可能性不会在每页重复描述，详见匹配器文档。

指令顺序

许多指令会操作 HTTP 处理器链。这些指令的执行顺序很重要，因此 Caddy 内置了默认顺序。

你可以用 order 全局选项 或 route 指令 覆盖/自定义此顺序。

tracing

map
vars
fs
root
log_append
log_skip
log_name

header
copy_response_headers # 仅在 reverse_proxy 的 handle_response 块中
request_body

redir

# 入站请求操作
method
rewrite
uri
try_files

# 中间件处理器；有些包裹响应
basic_auth
forward_auth
request_header
encode
push
intercept
templates

# 特殊路由与分发指令
invoke
handle
handle_path
route

# 通常响应请求的处理器
abort
error
copy_response # 仅在 reverse_proxy 的 handle_response 块中
respond
metrics
reverse_proxy
php_fastcgi
file_server
acme_server

排序算法

为方便使用，Caddyfile 适配器按以下规则排序指令：

  • 不同名称的指令按默认顺序排序。可用 order 全局选项 覆盖。插件指令_没有_顺序，因此应用 order 全局选项或 route 指令设置顺序。

  • 同名指令按匹配器排序。

    • 优先级最高的是只有单个路径匹配器的指令。

      路径匹配器按特异性从高到低排序。

      一般按路径长度排序。有个例外：如果路径以 * 结尾且两者路径内容相同，则无 * 的更具体，排在前。

      例如：

      • /foobar 比 /foo 更具体
      • /foo 比 /foo* 更具体
      • /foo/* 比 /foo* 更具体

    • 其他匹配器的指令按在 Caddyfile 中出现的顺序排序。

      包括有多个值的路径匹配器和命名匹配器。

    • 没有匹配器（即匹配所有请求）的指令排最后。

  • vars 指令按匹配器顺序反转排序，因为它涉及设置值，最具体的应最后评估。

  • route 指令内容忽略上述所有规则，保留块内指令出现顺序。