文档
一个 项目，由 ZeroSSL 支持

Caddyfile 教程

本教程将教您 HTTP Caddyfile 的基础知识，以便您可以快速轻松地生成美观且功能齐全的站点配置。

目标

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

先决条件

  • 基本的终端/命令行技能
  • 基本的文本编辑器技能
  • caddy 在您的 PATH 中

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

您应该键入的第一件事是您站点的 地址

localhost

然后按 Enter 键并键入您想要它执行的操作。对于本教程，使您的 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 tutorial</title>
	</head>
	<body>
		Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}
	</body>
</html>

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

输出为

Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}

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

localhost

templates
file_server browse

保存，然后重新加载浏览器选项卡。您应该看到

Page loaded at: Sun Apr 20 15:32:57 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 "I am 8080"
}

:8081 {
	respond "I am 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 之前，它将被扩展为

localhost:9055

file_server

您可以在 Caddyfile 中的任何位置使用环境变量，用于任意数量的令牌。

注释

您会发现最有帮助的最后一件事是：如果您想在 Caddyfile 中注释或记录任何内容，您可以使用注释，以 # 开头

# this starts a comment

进一步阅读