Nginx的ngx_http_addition_module追加内容模块是什么？如何配置使用？

Nginx的ngx_http_addition_module是一个很容易被忽视但非常实用的内置模块，它的作用是在响应体内容的前面或后面追加其他内容。典型的使用场景是：某个静态站点由大量HTML页面组成，现在需要给所有页面统一加上顶部公告栏或底部版权信息，如果逐个修改文件工作量巨大，而借助这个模块，只需要配置几行指令就能实现，完全不需要改动原始文件，也不需要后端程序参与。

模块的工作原理是什么

要理解ngx_http_addition_module，先要理解Nginx的子请求机制。当配置了追加内容的指令后，Nginx在向客户端发送主响应体之前或之后，会先发起一个内部子请求，这个子请求可以指向服务器上的任意URI，比如一个包含顶部导航的HTML片段文件。子请求返回的内容会被直接拼接到主响应的输出流中，客户端最终收到的就是拼接后的完整页面。

整个处理流程可以拆解为三步：第一步，Nginx完成主请求的处理，得到原始响应体，但暂时不发送给客户端；第二步，如果在配置中启用了add_before_body，Nginx会先执行该指令指向的子请求，并把子请求的响应体发送给客户端；第三步，发送完前置内容后再发送主响应体，如果还配置了add_after_body，主响应体发送完毕后继续追加子请求的内容。

需要注意的是，这个模块默认不会编译进Nginx，属于可选模块，需要在编译时通过--with-http_addition_module参数显式开启。可以执行nginx -V查看当前版本的编译参数，确认输出中是否包含这个选项。

核心指令与配置示例

模块只有两条核心指令，都是location级别可用的：add_before_body用于在响应体之前插入内容，add_after_body用于在响应体之后追加内容。两者的参数都是一个URI，指向提供追加内容的内部位置。下面通过一个完整的配置示例来说明用法。

server {
    listen 80;
    server_name www.ipipp.com;

    # 存放追加内容片段的位置，仅允许内部调用
    location /addition/ {
        internal;
        alias /data/fragments/;
    }

    location /docs/ {
        add_before_body /addition/header.html;
        add_after_body  /addition/footer.html;
        root /data/site;
    }
}

这个配置中，访问/docs/下的任何页面时，Nginx都会先输出header.html的内容，再输出页面本身，最后输出footer.html。配置里的internal指令很关键，它把/addition/标记为只能内部访问，外部直接请求该URI会返回404，避免片段文件被单独访问到。

还有一条容易忽略的指令addition_types，用于控制对哪些MIME类型的响应启用追加。默认情况下只对text/html类型生效，如果你的响应是其他类型，比如application/xhtml+xml，就需要显式声明：

location /docs/ {
    addition_types text/html application/xhtml+xml;
    add_after_body /addition/footer.html;
    root /data/site;
}

使用中的注意事项与方案对比

这个模块虽然简单，但有几个坑点需要留意。第一，它只在响应码为200和201等正常状态时生效，如果后端返回错误页面，追加内容不会出现。第二，追加动作对Nginx而言是透明的子请求，但要注意子请求不能指向需要再次触发追加的URI，否则可能造成逻辑混乱。第三，开启gzip时要小心，压缩输出流与内容追加可能产生冲突，建议把追加逻辑放在压缩之前的处理阶段，或者在相关location上仔细规划压缩配置。

与其他内容处理方案对比，各有适用场景。SSI（服务端包含）功能更强大，支持在页面任意位置插入内容，但需要修改HTML文件加入包含指令，而且要开启SSI解析会带来一定性能开销。sub_filter擅长做内容替换，可以替换字符串后再插入片段，但它是流式替换，处理大文件时要小心缓冲区问题。而ngx_http_addition_module的优势在于零侵入，只能加在头尾是它的局限也是它的特点，对于统一加导航、版权这类需求反而刚刚好，性能开销也是几个方案中最小的。

实际部署时还有一个建议：追加的片段文件应该尽量小，因为每个请求都会触发一次子请求，如果片段文件很大或子请求指向的后端响应慢，会明显拖累整体响应速度。如果是动态生成的内容，最好为子请求配置缓存，把片段的生成结果缓存起来，这样追加的开销基本可以忽略不计。掌握这些要点后，在静态站点、内部管理系统等场景中，这个模块能帮你省掉大量重复的页面修改工作。

Nginxngx_http_addition_module追加内容修改时间：2026-09-11 07:40:26