如何在ESP32平台libwebsocket库中启用gzip压缩功能

问题场景 #

在ESP32芯片上基于libwebsocket搭建Web服务器，静态文件存储于ROMFS分区，已完成JS/CSS/HTML资源的合并、精简（minify）优化，站点仅保留合并后的concatenated.js、concatenated.css文件，配置gzip压缩时出现两类异常：

• 未做额外配置时，静态资源GET请求响应头仅返回content-type: text/javascript，无压缩相关标识，服务器未自动执行压缩
• 测试方案1：构建ROMFS时仅存入预压缩的concatenated.js.gz文件，访问/concatenated.js路径直接返回404错误
• 测试方案2：构建ROMFS时同时存入原文件与对应.gz后缀压缩文件，服务器始终返回未压缩原文件，不会自动选择压缩版本传输

根因说明 #

libwebsocket的静态gzip传输能力默认处于关闭状态：既不会在运行时自动压缩静态文件（ESP32等MCU平台算力、内存不足，也不推荐开启动态压缩），也不会自动扫描同目录下的.gz后缀文件做内容协商，必须手动开启编译选项、配置挂载规则后才会生效。

正确配置步骤 #

1. 开启libwebsocket编译阶段gzip相关选项 #

在libwebsocket的编译配置入口（ESP-IDF环境下可通过menuconfig进入libwebsocket配置页，或直接添加编译宏）开启以下选项：

• 开启LWS_WITH_GZIP：启用核心gzip编解码能力
• 开启LWS_WITH_GZIP_INFLATE：启用gzip流传输支持
• 确认LWS_WITH_STATIC已开启：静态文件服务基础能力
• 确认LWS_WITH_FS_ROMFS已开启：ROMFS文件系统后端适配

2. 按规范存放预压缩静态文件 #

使用标准gzip工具（压缩等级选默认6即可，不要使用自定义特殊压缩参数）对精简后的JS/CSS/HTML文件做预压缩，压缩后文件命名为「原文件名.gz」，和原文件放在ROMFS的同层级目录下，目录结构参考：

/romfs_webroot/
├─ index.html
├─ index.html.gz
├─ concatenated.js
├─ concatenated.js.gz
├─ concatenated.css
└─ concatenated.css.gz

注意：不要删除非压缩的原文件，遇到不支持gzip的老旧客户端时，libwebsocket需要回退返回原文件

3. 静态文件挂载配置添加gzip标志 #

初始化libwebsocket HTTP服务时，给静态文件挂载结构体struct lws_http_mount添加gzip协商标志位，核心配置参考：

static const struct lws_http_mount web_mount = {
    .mount_next = NULL,
    .mountpoint = "/",
    .mountpoint_len = 1,
    .origin = "/romfs_webroot",
    .def = "index.html",
    .cache_max_age = 86400,
    // 核心配置：开启gzip静态文件自动协商
    .flags = LWSMPROT_FILES | LWSMPROT_FLAG_GZIP,
};

LWSMPROT_FLAG_GZIP是触发gzip逻辑的关键开关：开启后libwebsocket才会检查客户端请求的Accept-Encoding头，匹配到gzip支持时自动查找同路径的.gz文件返回。

4. 生效验证 #

配置完成后满足以下条件即会返回压缩资源：

• 客户端请求头携带Accept-Encoding: gzip（Chrome、Firefox等现代浏览器默认自动携带）
• 请求路径下存在匹配的.gz预压缩文件且文件无损坏
• 响应头会自动添加Content-Encoding: gzip标识，Content-Length为压缩后文件大小

常见踩坑点 #

• 不要将.gz文件直接作为独立路由映射：直接访问.gz路径会被识别为application/gzip下载类型，无法作为JS/CSS被页面解析
• 预压缩完成后先在本地验证gz文件完整性，损坏的gz文件会被libwebsocket直接跳过，自动回退返回非压缩原文件
• 不要尝试开启动态gzip压缩：ESP32的RAM和CPU算力不足以支撑运行时压缩，会导致响应延迟飙升甚至服务崩溃

内容的提问来源于stack exchange，提问作者Tom