Caddyfile 指令

指令是在站点块内出现的功能关键字。有时，它们可以打开自己的块，块中可以包含子指令，但除非另有说明，指令不能在其他指令内部使用。例如，你不能在 file_server 块内使用 basic_auth，因为 file_server 并不知道如何进行身份验证。然而，你可以在像 handle 和 route 这样的特殊指令块中使用某些指令，因为它们是专门用于分组 HTTP 处理器指令的。

• 语法
• 指令顺序
• 排序算法

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

语法

每个指令的语法看起来类似于：

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

尖括号 表示将被实际值替换的标记（token）。

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

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

子指令通常是可选的，除非另有文档说明，即使它们没有出现在[brackets]中也是如此。

匹配器（Matchers）

大多数——但不是全部——指令接受匹配器标记，用于过滤请求。匹配器标记通常是可选的。如果你在某个指令的语法中看到如下所示，则该指令支持匹配器：

[<matcher>]

因为匹配器标记的工作方式相同，所以为了减少重复，各种匹配器的可能性不会在每一页都详述。请参阅匹配器文档了解语法的详细说明。

指令顺序

许多指令会操作 HTTP 处理器链。那些指令的评估顺序很重要，因此 Caddy 中硬编码了一个默认排序。

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

tracing

map
vars
fs
root
log_append
log_skip
log_name

header
copy_response_headers # only in reverse_proxy's handle_response block
request_body

redir

# incoming request manipulation
method
rewrite
uri
try_files

# middleware handlers; some wrap responses
basic_auth
forward_auth
request_header
encode
push
intercept
templates

# special routing & dispatching directives
invoke
handle
handle_path
route

# handlers that typically respond to requests
abort
error
copy_response # only in reverse_proxy's handle_response block
respond
metrics
reverse_proxy
php_fastcgi
file_server
acme_server

排序算法

为了便于使用，Caddyfile 适配器根据以下规则对指令进行排序：

• 不同名称的指令按它们在默认顺序中的位置排序。默认顺序可以通过order 全局选项覆盖。来自插件的指令没有预设顺序，因此应使用order 全局选项或route 指令来为其设置顺序。

• 相同名称的指令根据它们的匹配器进行排序。

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

    路径匹配器按具体性排序，从最具体到最不具体。

    通常，这是通过按路径匹配器的长度排序来实现的。有一个例外：如果路径以 * 结尾且两个匹配器的路径在其他方面相同，则没有 * 的匹配器被视为更具体并排在更前面。

    例如：

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

  • 具有任何其他匹配器的指令按它们在 Caddyfile 中出现的顺序排序。

    这包括具有多个值的路径匹配器，以及命名匹配器。

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

• vars 指令的按匹配器排序是反向的，因为它涉及设置可能相互覆盖的值，因此应该最后评估最具体的匹配器。

• route 指令的内容忽略上述所有规则，并保留指令在其中出现的顺序。