ngx_http_addition_module 是 Nginx 官方过滤模块，支持在 text/html 响应体首尾插入静态文件（如页头页脚），需编译启用，不支持变量、SSI、Lua 及压缩响应，须注意 MIME 类型与 HTML 结构合法性。
ngx_http_addition_module 是 Nginx 官方提供的一个过滤模块，支持在响应体的开头（add_before_body）和结尾（add_after_body）插入静态内容，常用于添加统一的页头（header）、页脚（footer）、统计代码或免责声明等。它只对 200 响应且 Content-Type 为 text/html 的页面生效（默认行为），不适用于 JSON、CSS、JS 或二进制响应。
启用模块并确认支持
该模块不是默认编译进所有 Nginx 版本的。需确认你的 Nginx 已启用：
- 执行
nginx -V 2>&1 | grep -o with-http-addition-module，若输出存在则已编译支持； - 若未启用，需重新编译 Nginx 并添加
--with-http-addition-module参数； - OpenResty 默认包含此模块，无需额外编译。
配置 add_before_body 和 add_after_body
在 location 块中使用，指定要插入的本地文件路径（相对 Nginx 配置目录）或 URI（需配合 addition_types 和后端支持）：
-
add_before_body /includes/header.html;—— 插入页头 HTML 文件（路径相对于root或alias）； -
add_after_body /includes/footer.html;—— 插入页脚 HTML 文件； - 确保
/includes/header.html和/includes/footer.html可被 Nginx 读取（权限正确、路径存在）； - 注意：Nginx 不会解析插入文件中的 SSI、变量或 Lua 代码，仅作纯文本拼接。
控制生效范围与 MIME 类型
默认只处理 text/html 响应。如需支持其他类型（例如 application/xhtml+xml），需显式声明：
addition_types text/html application/xhtml+xml;- 可放在
http、server或location块中，作用域内生效； - 避免对 API 接口（如
/api/）启用，否则可能破坏 JSON 格式 —— 应用在明确的 HTML 页面 location 下，例如location / { ... }或location ~ \.html$ { ... }。
常见问题与注意事项
该模块简单但有明确限制，使用时需留意：
- 不支持动态内容：无法嵌入 $uri、$arg_* 等变量，也不能执行 Lua 或 SSI；如需动态页脚，应改用
sub_filter+ 后端模板，或用 OpenResty 的content_by_lua_block； - 响应必须是未压缩的：若启用了
gzip on，addition 模块会在压缩前插入，但部分客户端可能因 HTML 结构异常报错 —— 建议关闭 gzip 或确保插入内容合法闭合； - 不处理 304、错误页（4xx/5xx）、代理响应中禁用 addition 的上游设置；
- 插入内容需符合 HTML 结构逻辑，例如不要在
<head>外直接写<script>，避免破坏渲染。
