caddy配置文件详解

简介

Caddy 是用 Go 编写的多平台 Web 服务器，支持 HTTP/1.1、HTTP/2、HTTP/3，默认自动 HTTPS。它的原生配置格式是 JSON，为方便编写另提供 Caddyfile 作为配置入口，运行时会自动把 Caddyfile 转换为 JSON。下面梳理 Caddyfile 的结构、指令、匹配器与全局选项等概念，面向刚从 Nginx 迁移、需要快速部署反向代理与 HTTPS 站点的运维者和开发者，核心优势是少量配置即可得到可用的站点与证书。

核心功能

• 自动 HTTPS：站点配置域名后默认自动启用 HTTPS，无需手工申请和部署证书。
• 多协议支持：同时支持 HTTP/1.1、HTTP/2、HTTP/3，可直接对外提供新版 HTTP 协议服务。
• 双配置形态：原生配置为 JSON，Caddyfile 作为编写接口，运行时自动转换为 JSON 交给程序使用。
• 结构化语法：由块（blocks）、指令（directives）、token 与引号规则组成，层级清晰。
• 地址与匹配器：地址行决定哪些请求进入该站点块，匹配器对请求做条件筛选，指令只处理匹配的请求。
• 配置热重载：Caddyfile 变更时可重新加载；也可通过 HTTP API 提交配置，实现零停机变更。
• 可扩展：Go 编写、跨平台，官方软件包只含标准模块，第三方插件可用 xcaddy 从源码构建。

使用场景

• 个人站点快速上线 HTTPS：写一个域名块即可获得证书，第三方经验认为个人站点适合用 Caddy、企业站点常用 Nginx，选型以自身需求为准。
• 反向代理后端服务：GoToSocial 官方文档专门给出用 Caddy 做反向代理的配置，阿里云开发者社区的指南也包含反向代理与日志示例。
• 镜像或聚合站点部署：第三方教程用监听 :80 的站点块把请求转发到上游站点，改一处地址即可切换源站。
• 需要 HTTP/3 的站点：协议支持覆盖 HTTP/1.1 到 HTTP/3，适合想直接对外提供 HTTP/3 的服务。
• 需要第三方插件的定制部署：官方包不含第三方模块，可用 xcaddy 从源码构建带插件的 caddy 可执行文件。
• 从旧版本或 Nginx 迁移：可参考 Caddy 配置升级指南，把旧写法逐条改为当前块与指令结构。

Caddyfile 结构速查

• 全局选项块：位于文件最顶部、由花括号包裹的块，用于设置进程级选项，与具体站点分离。
• 站点地址：块首的地址行，可以是域名，也可以是 :80 这类监听地址，决定哪些请求进入该块。
• 指令：块内的具体动作，例如反向代理、日志等，负责真正处理请求。
• 匹配器：附加在指令前的条件，用来筛选请求方法、路径等，只有匹配的请求才被该指令处理。
• token 与引号：配置按空白切分为 token，值内含空格时需要用引号包裹，否则会被拆成多个 token。
• 嵌套块：指令后跟花括号可展开子配置，用于给单条指令补充更细的参数。

与同类方案的区别

• 配置来源不同：Nginx 只有自己的指令语法，Caddy 原生配置是 JSON，Caddyfile 只是为方便编写提供的接口。
• HTTPS 成本不同：Caddy 默认自动 HTTPS，域名指向即可用；其他方案通常要自行处理证书申请与续期。
• 协议覆盖不同：Caddy 支持 HTTP/1.1、HTTP/2、HTTP/3，多平台运行，由 Go 编写。
• 扩展方式不同：Caddy 官方软件包只含标准模块，扩展需用 xcaddy 从源码构建或走下载页面。
• 选型经验：第三方文章建议个人站点用 Caddy、企业站点用 Nginx，另有用户反馈 Caddy 对新手更友好，最终以实际业务为准。

安装与获取步骤

1. 确定获取渠道：官方软件包（只含标准模块）、官方下载页面，或从源码构建；安装文档见 https://caddyserver.com/docs/install 与中文文档 https://caddy2.dengxiaolong.com/docs/install。
2. 需要第三方插件时，用 xcaddy 从源码构建 caddy 可执行文件，或使用下载页面提供的构建，具体命令以官方页面为准。
3. 编写 Caddyfile（无扩展名），可放在任意目录，第三方教程中的常见路径为 /usr/local/caddy/Caddyfile，内容从全局选项与站点地址块写起。
4. 按入门指南顺序推进：运行守护进程、体验 API、给 Caddy 加载配置、验证配置，验证通过后再投入使用，见 https://caddy2.dengxiaolong.com/docs/getting-started。
5. 作为系统服务运行时，可参考 https://github.com/caddyserver/dist/blob/master/init/caddy.service 中的服务单元文件。
6. 后续修改 Caddyfile 后执行重新加载，使新配置生效；需要零停机时改用 HTTP API 提交配置。

注意事项

• 官方软件包只含标准模块，第三方插件必须用 xcaddy 从源码构建或走下载页面，否则对应指令不可用。
• Caddyfile 只是编写接口，排查问题时应确认转换后的 JSON，实际生效的是转换结果。
• 配置文件路径不固定，可放任何位置但需在启动时指定；第三方教程给出的路径仅供参考，以官方页面为准。
• 网络上不少教程沿用 Caddy 1 写法（例如 proxy 指令），与当前块加指令的结构不兼容，直接照抄会报错。
• 配置改动不会自动生效，需要重新加载；要避免服务中断就通过 HTTP API 提交配置。
• 版本号、发布日期、模块清单等信息以官方页面为准，不要凭旧文章的记忆填写。