文档
一个 项目，由 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://127.0.0.1/caddy.html

输出是

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

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

localhost

templates
file_server browse

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

Page loaded at: Mon Mar 10 17:17:45 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

进一步阅读