Python用Gzip压缩JSON和静态资源方法

本文深入解析了Python Web开发中Gzip压缩JSON响应与静态资源的常见陷阱与最佳实践：默认情况下各类框架的gzip中间件均不压缩application/json，需显式配置compressible_types；静态文件因不经过中间件流程，必须依赖预压缩（如构建时生成.gz文件）或反向代理（如Nginx的gzip_static）来实现高效压缩；而缺失Vary: Accept-Encoding响应头则可能导致缓存污染与客户端解析失败，必须确保其正确设置——三者缺一不可，否则看似启用的压缩实则形同虚设。

为什么 gzip 中间件没压上 JSON 响应？

默认情况下，多数 Python Web 框架的 gzip 中间件只压缩 text/html、text/css、application/javascript 这类 MIME 类型，而 application/json 通常被排除在外——哪怕你明确设置了 Content-Encoding: gzip 请求头，响应体依然明文返回。

• 检查中间件配置中的 mime_types 或 compressible_types 参数，确认是否包含 "application/json"
• Django 的 GZipMiddleware 默认不处理 JSON；FastAPI 的 GzipMiddleware 默认也不含 application/json；Starlette 同理
• 某些中间件（如 starlette.middleware.gzip.GZipMiddleware）允许传入 compressible_types 列表，直接补上即可：

  app.add_middleware(GZipMiddleware, compressible_types={"application/json", "text/html", "application/javascript"})

• 注意顺序：Gzip 中间件必须在路由/视图中间件之后、响应生成之前生效，否则 JSON 已经序列化成 bytes 就无法再压缩

gzip 压缩静态资源时路径没生效？

静态文件本身不经过中间件逻辑——GZipMiddleware 只作用于动态响应。想压缩 /static/js/app.js 这类文件，得靠预压缩或反向代理（如 Nginx），或者用构建工具生成 .js.gz 文件并配置服务器自动响应 Accept-Encoding: gzip。

• 不要指望 GZipMiddleware 自动读取并压缩磁盘上的 .css 或 .js 文件；它只对内存中生成的响应体做流式压缩
• 若用 whitenoise（Django）或 StaticFilesConfig（FastAPI），需额外启用其内置压缩支持，例如 whitenoise 的 WHITENOISE_USE_FINDERS = True 和 WHITENOISE_AUTOREFRESH = True 不起压缩作用，必须设 WHITENOISE_COMPRESS = True
• 更稳妥的做法：构建阶段用 gzip -k file.js 生成 file.js.gz，再让服务器（如 Nginx）配 gzip_static on;，这样零运行时开销

压缩后响应头缺失 Vary: Accept-Encoding？

这个响应头不是可选的——它告诉缓存层（CDN、浏览器、代理）：同一个 URL 的响应可能因请求头不同而不同。没有它，gzip 压缩后的响应可能被错误地缓存并返回给不支持 gzip 的客户端，导致乱码或解析失败。

• 大多数成熟中间件（如 Starlette、Django 的 GZipMiddleware）会自动加 Vary: Accept-Encoding，但自定义中间件或老版本可能漏掉
• 手动加的方法很简单：在压缩完响应体后，执行 response.headers["Vary"] = "Accept-Encoding"（注意不要覆盖已有 Vary 值，需合并）
• 如果用了多层缓存（比如 Cloudflare + Nginx + 应用），某一层删掉了 Vary，问题会变得隐蔽——建议用 curl -I https://yoursite.com/api/data 实测响应头

压缩小 JSON（

gzip 对极短文本压缩收益低，且压缩过程本身有 CPU 开销。实测表明，小于 ~500 字节的 JSON，压缩后体积可能不变甚至略增，而耗时增加 0.5–2ms（取决于 Python 环境和 zlib 设置）。

• 中间件一般提供 minimum_size 参数（如 Starlette 的 minimum_size=1000），建议设为 1000 或 1500，跳过微小响应
• 不要全局开启压缩后就不管了；配合日志或监控，观察实际压缩率（len(compressed)/len(original)）和延迟分布
• 如果 API 大量返回 {"ok": true} 这类响应，考虑用 gzip.compress(b'{"ok":true}', level=1) 测试真实开销，而不是依赖默认 level=6

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python用Gzip压缩JSON和静态资源方法》文章吧，也可关注golang学习网公众号了解相关技术文章。