Tengine concat 模块详解:用 `??` 合并静态资源、减少 HTTP 请求
Tengine concat 模块详解:用 ?? 合并静态资源、减少 HTTP 请求
导读
ngx_http_concat_module 是 Tengine 内置的一个 HTTP 模块,功能类似于 Apache 的 mod_concat:它允许客户端在一个请求中通过 ?? 分隔符列出多个文件,服务器把多个静态文件合并进一个响应报文中返回,从而显著减少浏览器对 JS/CSS 等静态资源的请求次数、降低连接开销。阅读本文后,你将掌握 concat 模块的请求格式、全部 6 个配置指令的语义与默认值、完整的编译安装步骤,以及其底层源码实现与测试用例的验证方式。
一、模块介绍与核心思想
该模块类似于 Apache 中的 mod_concat 模块,用于合并多个文件到一个响应报文中。它解决的是 Web 前端性能优化中非常经典的问题:减少 HTTP 请求数。当页面需要引入多个 JS 或 CSS 文件时,常规做法是多次请求;启用 concat 后,一次请求即可拉回全部文件内容,服务端在返回时拼接各文件字节流,并统一设置响应头。
请求参数格式
请求参数需要用两个问号(??)引出待合并的文件列表,例如:
http://example.com/??style1.css,style2.css,foo/style3.css
??之后的逗号分隔列表中的每一项都是一个相对于当前 location 根目录的文件路径;- 文件名可以带子目录(如上面的
foo/style3.css)。
参数中某个文件位置若只包含一个 ?,则 ? 后面表示该文件的版本号(用于缓存刷新),例如:
http://example.com/??style1.css,style2.css,foo/style3.css?v=102234
这里 ?v=102234 仅被解析为版本标记,不会被拼进实际文件路径,因此同一组文件换个版本号即可强制浏览器重新拉取,而不必修改文件名。
二、工作原理:从源码看请求处理全流程
concat 模块的完整实现位于 modules/ngx_http_concat_module/ngx_http_concat_module.c(共 549 行),模块在 ngx_http_concat_init 中被注册进 HTTP 的 CONTENT 阶段(ngx_http_concat_module.c#L533-L549)。核心处理函数 ngx_http_concat_handler(ngx_http_concat_module.c#L118-L430)执行以下关键步骤:
- 前置过滤:URI 必须以
/结尾(r->uri.data[r->uri.len - 1] != '/'时直接返回NGX_DECLINED,把请求交给其他模块处理);只处理GET和HEAD方法;模块未开启(!clcf->enable)时同样直接放行。 - 参数校验:要求
r->args.len >= 2且第一个字符必须是?,否则不处理。 - 解析文件列表:遍历 args 字符串,用
,切分文件路径,用?识别版本号(对应timestamp标记),逐个调用ngx_http_concat_add_path生成完整文件路径(ngx_http_concat_module.c#L181-L221)。 - 类型检查:根据每个文件的扩展名设置
Content-Type,再与concat_types配置的 MIME 类型集合比对(ngx_http_test_content_type),不在允许类型内的文件会导致请求直接返回 400(ngx_http_concat_module.c#L245-L253)。 - 同类型校验:若
concat_unique on,所有文件的内容类型必须完全一致,否则返回 400(ngx_http_concat_module.c#L255-L269)。 - 打开文件并拼装输出链:通过
ngx_open_cached_file打开每个文件(复用 open_file_cache,ngx_http_concat_module.c#L271-L321),把每个文件映射为一个ngx_buf_t挂到输出链上,并累加Content-Length、记录最大的mtime作为Last-Modified。 - 输出响应:设置
200 OK、Content-Length、Last-Modified后通过ngx_http_output_filter一次性下发(ngx_http_concat_module.c#L411-L429)。
其中 ngx_http_concat_add_path(ngx_http_concat_module.c#L433-L480)还承担两类安全校验:
- 空文件名:
p == v时记录 "client sent zero concat filename" 并返回 400; - 文件数超限:
uris->nelts >= max时记录 "client sent too many concat filenames" 并返回 400; - 路径安全性:调用
ngx_http_parse_unsafe_uri校验拼接后的路径,防止路径穿越等非法 URI。
此外,空的文件会被直接跳过(of.size == 0 时 continue,ngx_http_concat_module.c#L333-L335),不会影响整体输出。
三、配置指令详解
模块共提供 6 个指令,全部支持 http, server, location 三级上下文,指令解析定义见 ngx_http_concat_module.c#L39-L84,默认值在 ngx_http_concat_merge_loc_conf 中合并生效(ngx_http_concat_module.c#L509-L530)。
concat
- 语法:
concat on | off - 默认值:
concat off - 上下文:
http, server, location
在配置的地方使模块生效或失效。源码中对应 enable 字段,默认合并值为 0(关闭)。
concat_types
- 语法:
concat_types MIME types - 默认值:
concat_types: application/javascript text/css(文档中写作application/x-javascript text/css,源码默认类型定义见 ngx_http_concat_module.c#L32-L36) - 上下文:
http, server, location
定义可以被接受的 MIME 类型。只有扩展名解析出的 Content-Type 落在该集合内的文件才会被合并,其他类型的文件(如图片、HTML)会导致请求返回 400。可以追加更多类型,例如:
concat_types text/css application/javascript application/x-javascript;
concat_unique
- 语法:
concat_unique on | off - 默认值:
concat_unique on - 上下文:
http, server, location
定义是否只接受相同类型的文件。例如请求:
http://example.com/static/??foo.css,bar/foobaz.js
- 配置为
concat_unique on:由于foo.css与bar/foobaz.js类型不同,返回 400; - 配置为
concat_unique off:两个文件会被合并返回。
源码中对应 unique 字段,默认合并值为 1(开启),比较逻辑见 ngx_http_concat_module.c#L255-L269。
concat_max_files
- 语法:
concat_max_files number - 默认值:
concat_max_files 10 - 上下文:
http, server, location
定义单次请求最大能接受的文件数量。超过该数量的请求会在 ngx_http_concat_add_path 中直接返回 400(ngx_http_concat_module.c#L447-L451),既防止单个 URL 无限膨胀,也避免恶意构造超长请求消耗资源。
concat_delimiter
- 语法:
concat_delimiter string - 默认值:无
- 上下文:
http, server, location
定义在合并的文件之间插入的分隔符。例如:
http://example.com/??1.js,2.js
如果配置为 concat_delimiter "\n",响应会在 1.js 和 2.js 两个文件内容之间插入一个换行符(\n)。源码中分隔符以内存 buf 形式插入到两个文件 buf 之间,并计入 Content-Length(ngx_http_concat_module.c#L386-L408)。这一指令对某些需要文件间明确分隔(例如 JSONP 场景、避免 ; 缺失导致语法错误)的场景非常实用。
concat_ignore_file_error
- 语法:
concat_ignore_file_error on | off - 默认值:
concat_ignore_file_error off - 上下文:
http, server, location
定义模块是否忽略文件不存在(404)或者没有权限(403)错误。开启后,NGX_HTTP_NOT_FOUND 与 NGX_HTTP_FORBIDDEN 两种错误对应的文件会被跳过(continue),其余文件照常合并返回;关闭时任何一个文件出错都会直接返回对应错误码(ngx_http_concat_module.c#L314-L318)。
四、完整配置示例
下面是一个可直接套用的配置片段,展示了按 location 差异化启用 concat 的典型做法:
location /static/css/ {
concat on;
concat_max_files 20;
concat_types text/css;
}
location /static/js/ {
concat on;
concat_max_files 30;
concat_types application/javascript application/x-javascript;
concat_delimiter "\n";
}
- CSS 目录最多合并 20 个文件,且只接受
text/css类型; - JS 目录最多合并 30 个文件,并在每个文件之间插入换行,避免多个脚本拼接后因缺少换行产生语法歧义。
配置生效后即可通过如下 URL 访问(假设站点根目录下有对应文件):
http://example.com/static/js/??a.js,b.js,c.js?v=20240101
需要提醒的是:concat 依赖 URL 中的 ?? 参数,通常与前端构建工具配合使用,由页面模板在运行时动态拼出合并 URL,而不是手写死所有文件列表。
五、编译与安装
concat 模块的构建脚本位于 modules/ngx_http_concat_module/config,它同时兼容新版($ngx_module_link)与旧版 nginx 的 addon 构建方式,模块类型为 HTTP_AUX_FILTER。在 Tengine 源码根目录下按以下步骤安装:
-
编译 concat 模块。configure 时二选一:
./configure --add-module=modules/ngx_http_concat_module # 或编译为动态模块: ./configure --add-dynamic-module=modules/ngx_http_concat_module--add-module=modules/ngx_http_concat_module:模块被静态编译进 Tengine;--add-dynamic-module=modules/ngx_http_concat_module:模块被编译成动态模块(生成.so),之后通过load_module指令在nginx.conf中加载。
-
编译并安装:
make && make install -
配置 concat 的配置项:按上一节示例在
http、server或location块中写入concat等指令。 -
运行:启动(或
nginx -s reload重载)Tengine,即可通过??格式 URL 访问合并资源。
六、测试验证:仓库内已有的完整回归用例
仓库自带的测试用例 tests/nginx-tests/tengine-tests/concat.t 覆盖了 concat 模块的绝大多数行为,共规划 168 个断言,可直接作为功能正确性的验证依据。测试中覆盖的关键场景包括:
- concat on / off:开启时
GET /concatFile/??hello.js,world.js返回拼接后的hello.jsworld.js;关闭时按普通请求处理。 - concat_unique on:混合类型请求(
??hello.js,world.css,jack.js)返回 400;同类型请求(??hello.js,world.js,jack.js)正常合并。 - concat_unique off:混合类型请求也会被合并(返回
hello.jsworld.cssjack.js)。 - 文件数量上限、类型过滤、版本号参数解析等行为也均有对应用例。
这些用例与文档 docs/modules/ngx_http_concat_cn.md 相互印证:文档描述的是指令语义与用法,测试则从端到端角度验证了真实 HTTP 请求下的响应行为。
七、注意事项与最佳实践
- 默认 MIME 类型以源码为准:模块源码中默认接受
application/javascript与text/css(ngx_http_concat_module.c#L32-L36),老文档中出现的application/x-javascript在新版本中已被替换,如需兼容旧浏览器可在concat_types中显式追加。 - 只对 GET/HEAD 生效:POST 等请求不会触发 concat 处理逻辑。
- URI 必须以
/结尾:concat 只在 location 对应的目录请求上生效,若 URL 不以/结尾则请求会被交给静态文件处理等其他模块。 - 合理设置 concat_max_files:默认 10 个文件,上限过大会让单个 URL 过长并放大恶意请求成本,建议按实际资源数量设置 20~30 即可。
- 版本号只用于刷新缓存:
?v=xxx不会被拼入文件路径,修改版本号即可强制客户端重新拉取合并结果,是配合 CDN 与浏览器缓存刷新的标准做法。 - 结合 open_file_cache:模块通过
ngx_open_cached_file打开文件,天然复用 core 模块的 open_file_cache 配置(open_file_cache、open_file_cache_valid等),高并发场景下建议按常规静态资源站点开启文件缓存以提升性能。