Gin框架默认不支持Brotli压缩，因Go标准库至今未内置Brotli实现，必须手动集成第三方库（如andybalholm/brotli）封装Writer并处理Content-Encoding、Vary头、Content-Length清除及HEAD请求兼容性；部署时需明确压缩责任边界，避免与Nginx重复压缩。
Gin 框架本身不内置 Brotli 压缩支持，必须通过中间件手动集成 brotli 库实现响应体压缩；不能依赖 Nginx 层代理压缩来“掩盖” Go 层未压缩的问题，尤其当 Gin 直连客户端（如内网 API、gRPC-Gateway 透传）时，Brotli 必须在 Go 进程内完成。
为什么 Gin 默认不支持 Brotli，而必须自己写中间件
Gin 的 Context.Writer 是一个包装了 http.ResponseWriter 的接口，它不干预响应体内容生成逻辑。官方只提供了 gzip.Gzip() 中间件（基于标准库 compress/gzip），但 Go 标准库至今（2026 年）仍未包含 Brotli 实现。所有可用的第三方 Brotli 库（如 github.com/andybalholm/brotli）都需自行封装 Writer，且必须处理：Content-Length 清零、Content-Encoding 注入、Vary 头补全、以及对 HEAD 请求的跳过逻辑。
常见错误现象：curl -H "Accept-Encoding: br" http://localhost:8080/api 返回无 Content-Encoding: br，或返回 500（因 Writer 被多次 WriteHeader）。
- Go 生态中唯一稳定、低内存占用的 Brotli 实现是
github.com/andybalholm/brotli（非 Google 官方 C 库绑定，纯 Go 实现，无 CGO 依赖） - 不要用
go.bug.st/brotli或旧版github.com/ulikunitz/xz分支——它们已归档、不维护，且存在并发 panic 风险 - 若项目已用
gzip.Gzip()，必须确保 Brotli 中间件注册顺序在它之前，否则 gzip 会提前封禁 Writer
如何写一个安全可用的 Brotli 响应压缩中间件
核心是实现 http.ResponseWriter 接口的包装器，并在 Write() 和 WriteHeader() 中注入压缩逻辑。关键点不是“能不能压”，而是“压得稳、不破头、不漏判”。
以下为最小可行中间件（Go 1.21+，兼容 Gin v1.9+）：
import (
"net/http"
"strings"
"github.com/andybalholm/brotli"
"github.com/gin-gonic/gin"
)
func Brotli() gin.HandlerFunc {
return func(c *gin.Context) {
ae := c.GetHeader("Accept-Encoding")
if !strings.Contains(ae, "br") {
c.Next()
return
}
// 只对 text/html、application/json 等文本类型启用
contentType := c.GetHeader("Content-Type")
if !strings.HasPrefix(contentType, "text/") &&
!strings.HasPrefix(contentType, "application/json") &&
!strings.HasPrefix(contentType, "application/javascript") &&
!strings.HasPrefix(contentType, "application/css") {
c.Next()
return
}
brWriter := &brotliResponseWriter{
ResponseWriter: c.Writer,
br: brotli.NewWriterLevel(c.Writer, 4),
}
c.Writer = brWriter
c.Next()
if brWriter.written {
brWriter.br.Close() // 必须显式 close，否则缓冲区不 flush
}
}
}
type brotliResponseWriter struct {
http.ResponseWriter
br *brotli.Writer
written bool
}
func (w *brotliResponseWriter) Write(p []byte) (int, error) {
if !w.written {
w.ResponseWriter.WriteHeader(http.StatusOK)
w.written = true
w.ResponseWriter.Header().Set("Content-Encoding", "br")
w.ResponseWriter.Header().Add("Vary", "Accept-Encoding")
// 移除 Content-Length：brotli 压缩后长度不可预知
w.ResponseWriter.Header().Del("Content-Length")
}
return w.br.Write(p)
}
func (w *brotliResponseWriter) WriteHeader(statusCode int) {
if !w.written {
w.written = true
w.ResponseWriter.WriteHeader(statusCode)
w.ResponseWriter.Header().Set("Content-Encoding", "br")
w.ResponseWriter.Header().Add("Vary", "Accept-Encoding")
w.ResponseWriter.Header().Del("Content-Length")
}
}
-
brotli.NewWriterLevel(w, 4)：Level 4 是 CPU 与压缩率的合理平衡点，Level 11 在高并发下易引发 Goroutine 阻塞 - 必须在
Write()和WriteHeader()中都判断!w.written，避免重复设置 header 导致 panic - HEAD 请求不会进
Write()，但会进WriteHeader()，所以两个方法都要处理 - 切勿在中间件里调用
c.Abort()后还尝试 write —— 此时w.written可能为 false，但ResponseWriter已被终止
与 Nginx Brotli 的协作边界在哪
当 Gin 前面挂了 Nginx，是否还要在 Gin 层做 Brotli？答案取决于部署拓扑：
- 若 Nginx 与 Gin 同机部署（Unix socket / localhost），且 Nginx 已配置
brotli on+brotli_static on，则 Gin 层应关闭所有压缩，由 Nginx 统一处理 - 若 Gin 是独立服务（如 Kubernetes Pod 内暴露 ClusterIP），且前端 CDN 不信任或无法解析 Go 服务的
Content-Encoding，则必须在 Gin 层压缩，Nginx 仅作反向代理透传 - 最危险的组合：
Nginx 开启 gzip + Gin 开启 brotli→ 客户端可能收到Content-Encoding: br,gzip（非法头），或 Nginx 把已压缩的 br 流再次 gzip，导致浏览器解压失败
验证方式很简单：curl -v -H "Accept-Encoding: br" http://your-api.com/health，检查响应头是否只有 Content-Encoding: br，且 Content-Length 显著小于未压缩时的值（例如 1KB JSON 压到 300B）。若出现 Content-Encoding: gzip, br 或解压乱码，说明链路中某层做了重复压缩。
真正容易被忽略的是错误响应路径：比如 c.JSON(500, gin.H{"error": "xxx"}) 这类 panic 后的 recovery 响应，往往绕过中间件。若没在 gin.Recovery() 后再挂一层 Brotli，500 响应就永远是明文——而线上故障时，这些响应恰恰最需要快速传输。
