Caddy如何高效托管并自动压缩静态文件？

Question

常见技术问题： 在使用 Caddy 托管静态网站时，尽管 `file_server` 默认启用 Brotli 和 Gzip 压缩（v2.6+），但实际请求中仍返回未压缩响应（如 `Content-Encoding` 缺失、`Content-Length` 未减小），或对 `.js/.css/.html` 外的文件（如 `.json`、`.svg`、`.woff2`）不压缩。进一步排查发现：Caddy 默认仅压缩符合 `text/*`、`application/javascript`、`application/json` 等白名单 MIME 类型的响应，且要求客户端明确声明 `Accept-Encoding: br,gzip`；若前端构建产物未设置正确 `Content-Type` 响应头（如通过 `header` 指令覆盖或静态文件无扩展名映射），或启用了 `encode zstd` 但客户端不支持，也会导致压缩失效。此外，在反向代理场景下误将 `encode` 放在 `reverse_proxy` 块内，而非 `file_server` 同级，亦会绕过压缩逻辑。如何精准配置 MIME 类型白名单、确保静态文件响应头正确，并验证压缩是否生效？

Answer 1

```html

一、现象层：压缩未生效的典型表征

• curl -H "Accept-Encoding: br,gzip" -I https://example.com/app.js 返回无 Content-Encoding 头
• 响应体大小与原始文件一致（Content-Length 未显著减小）
• .svg、.woff2、.json 等资源始终明文传输，浏览器 Network 面板显示 Encoded 列为空
• 使用 curl -v 可观察到服务端未返回 Vary: Accept-Encoding，暗示压缩逻辑未介入

二、机制层：Caddy v2.6+ 压缩决策的三重门控

Caddy 的 encode 模块（默认由 file_server 自动启用）执行压缩需同时满足：

1. 客户端声明：请求含 Accept-Encoding: br,gzip（注意：顺序无关，但必须显式存在）
2. MIME 白名单匹配：响应头 Content-Type 必须属于内置白名单（如 text/html, application/json, image/svg+xml），font/woff2 默认不包含
3. 作用域正确性：`encode` 必须与 `file_server` 或 `reverse_proxy` 同级嵌套，而非其子块内——否则被跳过

三、诊断层：五步精准归因法

步骤	命令/操作	预期成功信号
1. 检查客户端协商	curl -H "Accept-Encoding: br,gzip" -s -o /dev/null -w "%{size_download}\n" https://site.com/main.css	下载字节数显著小于本地文件
2. 校验响应头	curl -H "Accept-Encoding: br,gzip" -I https://site.com/data.json	含 Content-Encoding: br 和 Vary: Accept-Encoding
3. 验证 MIME 类型	curl -I https://site.com/icon.svg | grep "Content-Type"	应为 image/svg+xml（非 text/plain）

四、配置层：生产就绪的压缩策略

example.com {
    root * /var/www/html

    # ✅ 正确：encode 与 file_server 同级，显式扩展 MIME 白名单
    encode zstd br gzip {
        # 覆盖默认白名单，增加现代字体与矢量格式
        include application/json application/javascript text/css text/html image/svg+xml font/woff2 font/woff
        # 排除大二进制（避免 CPU 过载）
        exclude application/octet-stream
    }

    file_server {
        # ✅ 强制静态文件 Content-Type 映射（解决构建工具缺失扩展名问题）
        header /assets/* {
            Content-Type "font/woff2"
        }
        # ✅ 对无扩展名 JSON API 响应兜底
        header /api/* {
            Content-Type "application/json"
        }
    }

    # ❌ 错误示例（勿复制）：
    # reverse_proxy localhost:3000 {
    #   encode br gzip  ← 此处无效！encode 不作用于 reverse_proxy 内部响应
    # }
}

五、验证层：自动化回归检测脚本

以下 Bash 脚本可集成至 CI/CD 流程，验证关键资源压缩状态：

#!/bin/bash
RESOURCES=("/main.css" "/app.js" "/data.json" "/icon.svg" "/fonts/inter.woff2")
for path in "${RESOURCES[@]}"; do
  echo -n "$path: "
  enc=$(curl -s -I -H "Accept-Encoding: br,gzip" "https://example.com$path" | grep -i "content-encoding:" | cut -d' ' -f2 | tr -d '\r\n')
  size=$(curl -s -o /dev/null -w "%{size_download}" -H "Accept-Encoding: br,gzip" "https://example.com$path")
  orig=$(curl -s -o /dev/null -w "%{size_download}" "https://example.com$path")
  if [[ -z "$enc" ]] || [[ $size -ge $orig ]]; then
    echo "❌ FAILED (no encoding or no size reduction)"
  else
    ratio=$(awk "BEGIN {printf \"%.1f\", ($orig/$size)*100}")
    echo "✅ OK ($enc, $ratio% smaller)"
  fi
done

六、进阶层：MIME 类型映射的底层控制

Caddy 使用 http.stdlib 的 mime.TypeByExtension 查表，但可通过 mime 全局指令覆盖：

{
    mime {
        # 将 .svg 强制映射为 image/svg+xml（修复某些构建产物误设为 text/plain）
        .svg image/svg+xml
        # 支持现代字体格式
        .woff2 font/woff2
        .woff  font/woff
        .ttf   font/ttf
    }
}

七、可视化：压缩生效全流程图

graph LR A[Client Request] --> B{Has Accept-Encoding?} B -- Yes --> C{Response MIME in whitelist?} B -- No --> D[Skip encode] C -- Yes --> E[Apply best encoding
br > gzip > zstd] C -- No --> D E --> F[Set Content-Encoding
Vary: Accept-Encoding] F --> G[Return compressed body]

```