Tengine concat 模块详解:用 `??` 合并静态资源、减少 HTTP 请求

原创2026-09-21 16:51:551,446 阅读
文章标签:后端网络负载均衡API网关云原生网络安全

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)执行以下关键步骤:

  1. 前置过滤:URI 必须以 / 结尾(r->uri.data[r->uri.len - 1] != '/' 时直接返回 NGX_DECLINED,把请求交给其他模块处理);只处理 GET 和 HEAD 方法;模块未开启(!clcf->enable)时同样直接放行。
  2. 参数校验:要求 r->args.len >= 2 且第一个字符必须是 ?,否则不处理。
  3. 解析文件列表:遍历 args 字符串,用 , 切分文件路径,用 ? 识别版本号(对应 timestamp 标记),逐个调用 ngx_http_concat_add_path 生成完整文件路径(ngx_http_concat_module.c#L181-L221)。
  4. 类型检查:根据每个文件的扩展名设置 Content-Type,再与 concat_types 配置的 MIME 类型集合比对(ngx_http_test_content_type),不在允许类型内的文件会导致请求直接返回 400(ngx_http_concat_module.c#L245-L253)。
  5. 同类型校验:若 concat_unique on,所有文件的内容类型必须完全一致,否则返回 400(ngx_http_concat_module.c#L255-L269)。
  6. 打开文件并拼装输出链:通过 ngx_open_cached_file 打开每个文件(复用 open_file_cache,ngx_http_concat_module.c#L271-L321),把每个文件映射为一个 ngx_buf_t 挂到输出链上,并累加 Content-Length、记录最大的 mtime 作为 Last-Modified。
  7. 输出响应:设置 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 源码根目录下按以下步骤安装:

  1. 编译 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 中加载。
  2. 编译并安装:

    make && make install
    
  3. 配置 concat 的配置项:按上一节示例在 http、server 或 location 块中写入 concat 等指令。

  4. 运行:启动(或 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 等),高并发场景下建议按常规静态资源站点开启文件缓存以提升性能。
登录后查看全文
tengine