NGINX ngx_http_addition_module 模块响应体前后注入内容

一、模块概述

• 模块名称：ngx_http_addition_module
• 引入版本：自 0.7.9 起支持 addition_types，0.8.29 起支持“*”通配；
• 功能：对符合 MIME 类型的响应，在响应体前后分别插入指定子请求 URI 返回的内容；
• 默认状态：未内置，需要编译时加上 --with-http_addition_module。

二、编译启用

# 假设已下载 nginx 源码：
./configure --with-http_addition_module [其他参数...]
make
sudo make install

完成后可通过 nginx -V 查看是否出现 --with-http_addition_module 标志。

三、核心指令

1. add_before_body

add_before_body uri;

• 作用：在主响应体内容前，发起子请求 uri，并将子请求返回的响应体插入主响应中；
• 上下文：http、server、location；
• 取消继承：传入空字符串 add_before_body ""; 即可清除上级配置的前置注入。

2. add_after_body

add_after_body uri;

• 作用：在主响应体内容后，发起子请求 uri，并将子请求返回的响应体追加到主响应后；
• 上下文：同上；
• 取消继承：add_after_body "";

3. addition_types

addition_types mime-type ...;

• 默认值：仅对 text/html 响应生效；
• 扩展：可指定多种 MIME 类型，或使用 * 对任意类型生效（0.8.29+）；
• 上下文：http、server、location。

四、基本示例

http {
    server {
        listen 80;
        server_name example.com;

        # 对所有 text/html 响应，插入公共头与脚
        location / {
            add_before_body /common/header.html;
            add_after_body  /common/footer.html;
        }

        # 子请求返回的数据，仅做纯文本注入
        location = /common/header.html {
            default_type text/html;
            return 200 '<header><h1>欢迎访问 Example</h1></header>';
        }
        location = /common/footer.html {
            default_type text/html;
            return 200 '<footer><p>&copy; 2025 Example.com</p></footer>';
        }
    }
}

• 客户端访问 /index.html 时，NGINX 先读取原始文件内容，再分别向 /common/header.html、/common/footer.html 发起子请求，将两者内容前后拼接后返回。

五、进阶场景

1. 多类型注入

location /api/ {
    addition_types application/json text/plain;
    add_after_body  /injection/logging;
}

针对 JSON 接口或纯文本接口，也可注入调试信息或埋点脚本。

2. 条件注入

利用 if、map 等指令，按请求参数或 Header 控制是否注入：

map $arg_debug $do_add {
    default "";
    1       "/debug/info.html";
}

location / {
    add_after_body $do_add;
    addition_types *;
}

当请求携带 ?debug=1 时，才将 /debug/info.html 内容追加至任意 MIME 类型响应后。

3. 与缓存配合

若子请求内容稳定，可借助 proxy_cache 或 fastcgi_cache 缓存子请求，减少注入带来的性能开销。

六、性能与注意事项

1. 子请求开销
   • 每一次注入都伴随子请求，可能增加延迟；建议将静态注入内容放在内存 lua_shared_dict（OpenResty）或缓存模块中。
2. MIME 类型过滤
   • 默认仅对 text/html 注入；如果插入到二进制（如图片、下载包）将损坏响应，务必通过 addition_types 精确限定，或使用 * 时结合条件判断。
3. 继承与层级
   • 在 http/server 级定义全局注入，location 可覆盖：使用空参数清除继承。
4. 循环注入
   • 注意避免子请求 URI 又被自身注入，导致死循环；可通过精确 location = /uri 或在子请求中设置 add_before_body ""/add_after_body "" 取消注入。

七、总结

ngx_http_addition_module 提供了一种优雅的“响应体加料”手段，适合注入通用页头、页脚、埋点脚本及调试信息等场景。得益于子请求机制，可灵活复用已有模板或动态生成内容。结合 addition_types、条件判断与缓存优化，可在保证性能的前提下，实现高度可控的内容插入。希望本文示例与实践建议，能帮助你快速上手该模块，为你的 NGINX 服务增色添彩。