一、模塊概述
- 模塊名稱：
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>© 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 緩存子請求，減少注入帶來的性能開銷。
六、性能與注意事項
- 子請求開銷
- 每一次注入都伴隨子請求，可能增加延遲；建議將靜態注入內容放在內存
lua_shared_dict（OpenResty）或緩存模塊中。
- 每一次注入都伴隨子請求，可能增加延遲；建議將靜態注入內容放在內存
- MIME 類型過濾
- 默認僅對
text/html注入；如果插入到二進制（如圖片、下載包）將損壞響應，務必通過addition_types精確限定，或使用*時結合條件判斷。
- 默認僅對
- 繼承與層級
- 在
http/server級定義全局注入，location可覆蓋：使用空參數清除繼承。
- 在
- 循環注入
- 注意避免子請求 URI 又被自身注入，導致死循環；可通過精確
location = /uri或在子請求中設置add_before_body ""/add_after_body ""取消注入。
- 注意避免子請求 URI 又被自身注入，導致死循環；可通過精確
七、總結
ngx_http_addition_module 提供了一種優雅的“響應體加料”手段，適合注入通用頁頭、頁腳、埋點腳本及調試信息等場景。得益于子請求機制，可靈活復用已有模板或動態生成內容。結合 addition_types、條件判斷與緩存優化，可在保證性能的前提下，實現高度可控的內容插入。希望本文示例與實踐建議，能幫助你快速上手該模塊，為你的 NGINX 服務增色添彩。
