Caddyfile 教程

本教程将教你 HTTP Caddyfile 的基础知识，让你能够快速轻松地创建美观且功能完善的站点配置。

目标：

🔲 第一个站点
🔲 静态文件服务器
🔲 模板
🔲 压缩
🔲 多个站点
🔲 匹配器
🔲 环境变量
🔲 注释

前提条件：

基本的终端/命令行技能
基本的文本编辑器技能
caddy 在 PATH 环境变量中

创建一个名为 Caddyfile 的新文本文件（无扩展名）。

你应该输入的第一件事是你站点的地址：

localhost

然后按回车并输入你想要它做什么。对于本教程，让你的 Caddyfile 看起来像这样：

localhost

respond "Hello, world!"

保存后运行 Caddy（由于这是一个培训教程，我们将使用 --watch 标志，这样对 Caddyfile 的更改会自动应用）：

caddy run --watch

第一次运行时，系统会要求你输入密码。这是为了让 Caddy 能够通过 HTTPS 提供你的站点。

在浏览器中打开 localhost，你会看到你的 Web 服务器正在工作，并且支持 HTTPS！

这还不够令人兴奋，所以让我们将静态响应更改为启用目录列表的文件服务器：

localhost

file_server browse

保存你的 Caddyfile，然后刷新浏览器标签页。你应该会看到文件列表，如果当前目录中有索引文件，则会看到 HTML 页面。

添加功能

让我们为文件服务器添加一些有趣的功能：提供模板页面。创建一个新文件并粘贴以下内容：

<!DOCTYPE html>
<html>
	<head>
		<title>Caddy 教程</title>
	</head>
	<body>
		页面加载时间：{{now | date "Mon Jan 2 15:04:05 MST 2006"}}
	</body>
</html>

将其保存为当前目录中的 caddy.html 并在浏览器中加载：https://localhost/caddy.html

输出是：

页面加载时间：{{now | date "Mon Jan 2 15:04:05 MST 2006"}}

等一下。我们应该看到今天的日期。为什么没有生效？这是因为服务器还没有配置为评估模板！很容易修复，只需在 Caddyfile 中添加一行，使其看起来像这样：

localhost

templates
file_server browse

保存后，重新加载浏览器标签页。你应该会看到：

页面加载时间：Tue Jul 1 13:10:04 UTC 2025

使用 Caddy 的模板模块，你可以用静态文件做很多有用的事情，比如包含其他 HTML 文件、发出子请求、设置响应头、处理数据结构等等！

使用快速现代的压缩算法压缩响应是一个好习惯。让我们使用 encode 指令启用 Gzip 和 Zstandard 支持：

localhost

encode
templates
file_server browse

这就是启动一个半高级、生产就绪的站点的基本过程！

当你准备开启自动 HTTPS 时，只需将你的站点地址（在我们的教程中是 localhost）替换为你的域名。有关更多信息，请参阅我们的 HTTPS 快速入门指南。

多个站点

使用我们当前的 Caddyfile，我们只能有一个站点定义！只有第一行可以是站点的地址，然后文件的其余部分必须是该站点的指令。

但是我们可以很容易地添加更多站点！

我们目前的 Caddyfile：

localhost

encode
templates
file_server browse

等同于这个：

localhost {
	encode
	templates
	file_server browse
}

除了第二个允许我们添加更多站点。

通过用花括号 { } 包装我们的站点块，我们可以在同一个 Caddyfile 中定义多个不同的站点。

例如：

:8080 {
	respond "我是 8080"
}

:8081 {
	respond "我是 8081"
}

当用花括号包装站点块时，只有地址出现在花括号外，只有指令出现在花括号内。

对于共享相同配置的多个站点，你可以添加更多地址，例如：

:8080, :8081 {
	...
}

然后你可以定义任意多个不同的站点，只要每个地址都是唯一的。

匹配器

我们可能只想对某些请求应用一些指令。例如，假设我们想要同时拥有文件服务器和反向代理，但我们显然不能对每个请求都这样做！要么文件服务器会用静态文件写入响应，要么反向代理会将请求传递给后端并写回其响应。

这个配置不会像我们想要的那样工作（由于指令顺序，reverse_proxy 将优先）：

localhost

file_server
reverse_proxy 127.0.0.1:9005

在实践中，我们可能只想对 API 请求使用反向代理，即基本路径为 /api/ 的请求。这很容易通过添加匹配器标记来实现：

localhost

reverse_proxy /api/* 127.0.0.1:9005
file_server

好了；现在反向代理将优先处理所有以 /api/ 开头的请求。

我们刚刚添加的 /api/* 部分被称为匹配器标记。你可以通过它以正斜杠 / 开头并且出现在指令之后来判断它是一个匹配器标记（但你总是可以在指令文档中查找以确定）。

匹配器非常强大。你可以声明命名匹配器并使用 @name 来匹配不仅仅是请求路径！在继续之前，花点时间了解更多关于匹配器的信息！

环境变量

Caddyfile 适配器允许在解析 Caddyfile 之前替换环境变量。

首先，设置一个环境变量（在运行 Caddy 的同一个 shell 中）：

export SITE_ADDRESS=localhost:9055

然后你可以在 Caddyfile 中这样使用它：

{$SITE_ADDRESS}

file_server

注释

最后一件事，如果你想要在 Caddyfile 中备注或注释任何内容，你可以使用注释，以 # 开头：

# this starts a comment