建立 2026-09-15 更新 2026-09-15

Caddyfile

Caddyfile 是給人寫的設定格式，底層會轉成 Caddy 原生的 JSON。大多數網站手寫 Caddyfile 就夠；要大規模自動化再考慮直接用 JSON 與 Admin API。

官方完整說明：The Caddyfile、Caddyfile 教學、Caddyfile 觀念。

站台區塊

最小單位是「位址 + 指令」：

example.com {
    encode gzip
    file_server
}

• 位址可以是網域、localhost、:8080、http:// 或 https:// 開頭。有合法主機名時，預設走 HTTPS。
• 指令一行一個，常用的有 reverse_proxy、file_server、redir、header。指令有執行順序，不是單純由上往下。

多個站台就寫多個區塊：

www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    reverse_proxy localhost:3000
}

只有一個站台時，可以省略大括號，但多站台就一定要包起來。

全域選項

檔案最前面、單獨一組大括號，設定套用到整個程序，例如 email（憑證到期通知）、DNS 挑戰、關閉自動 HTTPS：

{
    email you@example.com
}

example.com {
    reverse_proxy 127.0.0.1:8080
}

完整列表見 Global options。不要把站台指令寫進這一段。

Matcher：只對部分請求生效

指令可以加 matcher，過濾路徑、主機或其他條件。具名 matcher 以 @ 開頭：

example.com {
    @api path /api/*
    reverse_proxy @api localhost:8080

    file_server
}

路徑 matcher 也常直接寫在指令後面：reverse_proxy /api/* localhost:8080。較複雜的條件（header、方法、副檔名）用 @名稱 比較好讀。

handle／handle_path 用來互斥分流，避免多條 reverse_proxy 搶同一請求，見 常用指令。

Snippet 與 import

重複的安全標頭或 TLS 設定可抽成 snippet，用 import 套用：

(headers) {
    header {
        X-Content-Type-Options nosniff
        Referrer-Policy strict-origin-when-cross-origin
    }
}

example.com {
    import headers
    reverse_proxy app:3000
}

也可以 import 其他檔案，把多個站台拆開維護。

環境變數

敏感值不要寫死在檔案裡：

example.com {
    reverse_proxy {$UPSTREAM}
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
}

{$VAR} 在載入 Caddyfile 時展開；{env.VAR} 在執行期讀。DNS 模組通常用後者。Token 用 systemd EnvironmentFile 或 Compose environment 注入。

檢查與重載

caddy validate --config Caddyfile
caddy adapt --config Caddyfile
caddy reload --config Caddyfile

adapt 會印出對應的 JSON，適合對照指令實際變成什麼。語法錯時 reload 會失敗並留下舊設定，網站不會帶著壞設定上線。

接下來依需求看 反向代理 或 靜態檔案。