玩转 Caddyfile：从零到精通的配置艺术

Caddyfile 的基本编写原则是：直观、自上而下、按块组合。

一、 Caddyfile 的核心结构解析

标准的 Caddyfile 结构非常固定，主要由 Site Block（站点块）、Matchers（匹配器） 和 Directives（指令） 组成。

1. 单站点基本结构

如果你的服务器只托管一个网站，甚至连最外层的大括号 {} 都可以省略：

代码段

# 这是一个单站点配置示例（# 号后是注释）
example.com {
    # 指令 (Directives) 写在这里
    file_server
}

2. 多站点基本结构

如果一台服务器要托管多个域名，用大括号将它们隔开即可：

代码段

# 站点 A：博客
blog.example.com {
    reverse_proxy localhost:2368
}

# 站点 B：静态官网
www.example.com {
    root * /var/www/html
    file_server
}

3. 全局配置块 (Global Options Block)

如果你需要配置一些全局生效的参数（如：全局电子邮箱、TLS 选项），必须把它放在 文件的最顶部，且没有域名：

代码段

{
    # 全局配置，注意最外面没有域名
    email your-email@example.com  # 用于 ACME 申请证书时接收过期通知
    http_port 80
    https_port 443
}

# 后面才是正常的站点配置
example.com {
    reverse_proxy localhost:8080
}

二、 必须掌握的 5 大核心指令 (Directives)

在站点块内部，每一行通常都是一个“指令”。以下是高频使用的 5 个核心指令：

1. root —— 指定网站根目录

• 语法：root [<matcher>] <path>
• 示例：root * /var/www/my-site （* 代表匹配所有请求路径）

2. file_server —— 开启静态文件服务

• 功能：让 Caddy 变成一个静态 Web 服务器。
• 进阶：file_server browse 可以在没有 index.html 时，自动生成一个现代化的文件下载列表页面。

3. reverse_proxy —— 反向代理（核心神技）

• 功能：把流量转发给后端的应用（如 Node.js, Go, Python, Docker 容器等）。

• 示例：
  代码段

  # 基础代理
  reverse_proxy localhost:3000
  
  # 负载均衡：流量平分给两个后端，并开启被动健康检查
  reverse_proxy 10.0.0.1:8080 10.0.0.2:8080 {
      lb_policy round_robin
      fail_duration 10s
  }
  

4. encode —— 开启响应压缩

• 功能：压缩网页体积，极大提升加载速度。
• 最佳实践：直接无脑写 encode gzip zstd（完美支持现代的 Zstandard 压缩和老旧的 Gzip）。

5. redir —— 重定向

• 功能：将请求跳转到其他 URL。
• 示例：redir https://newsite.com{uri} permanent（带路径永久重定向）。

三、 高级技巧：请求匹配器 (Matchers)

如果你只想对特定路径或特定条件进行代理或重定向，就需要用到“匹配器”。

1. 路径匹配（以 / 开头）

代码段

example.com {
    # 只有访问 /api/* 的时候才走反向代理
    reverse_proxy /api/* localhost:8080
  
    # 其他所有请求（*）走静态文件
    root * /var/www/html
    file_server
}

2. 命名匹配器（适合复杂逻辑）

使用 @ 符号可以自定义一个复合条件匹配器：

代码段

example.com {
    # 定义一个叫 @post_requests 的匹配器：必须是 POST 请求，且路径以 /submit 开头
    @post_requests {
        method POST
        path /submit*
    }

    # 对符合上述条件的请求应用特定指令
    reverse_proxy @post_requests localhost:9000
}

四、 4 大经典实战模板（直接抄作业）

为了方便读者，这里提供几个日常运维中最常用的 Caddyfile 模板：

模板 1：纯静态 SPA 应用（如 Vue / React 路由精修版）

解决前端单页应用刷新后 404 的问题：

代码段

example.com {
    root * /var/www/dist
    encode gzip zstd
  
    # 核心：尝试寻找文件，找不到就重定向到 index.html
    try_files {path} {path}/ /index.html
  
    file_server
}

模板 2：全能型 Web 服务（静态资源 + 后端 API）

代码段

api.example.com {
    encode gzip zstd

    # 1. 后端接口转发
    handle /api/* {
        reverse_proxy localhost:8080
    }

    # 2. 其他请求全部走前端静态网页
    handle {
        root * /var/www/frontend
        file_server
    }
}

模板 3：内网开发 / 无域名环境（自动本地证书）

如果你在局域网内开发，没有公网域名，又想要 HTTPS：

代码段

# 使用内网 IP 或本地 localhost
192.168.1.100:443, localhost:443 {
    # 启用 Caddy 内置的本地 CA，自动生成并信任自签名证书
    tls internal
  
    reverse_proxy localhost:3000
}

模板 4：非标准端口与特定 ACME 验证

如果你的 80/443 端口被封禁，可以改用其他端口，并通过 DNS 插件验证申请证书（以 Cloudflare 为例）：

代码段

example.com:8443 {
    # 使用 DNS 挑战完成证书申请
    tls {
        dns cloudflare {env.CLOUDFLARE_AUTH_TOKEN}
    }
  
    reverse_proxy localhost:5000
}

💡 提示：编写完如何检验？

每次修改完 Caddyfile，强烈建议在终端执行以下命令进行语法检查：

Bash

caddy validate --config /path/to/Caddyfile

如果没有报错，再执行 caddy reload 刷新配置，稳如泰山！