Nginx 自定义模块开发基础及环境搭建

开发Nginx自定义模块核心在于源码级集成，需装齐gcc、PCRE、zlib、OpenSSL四类依赖，组织含config文件的模块目录，通过--add-module指定路径，经configure、make编译后用nginx -t验证指令加载与逻辑生效。

开发 Nginx 自定义模块，核心在于环境可编译、代码可加载、逻辑可验证。它不是改配置那么简单，而是要和 Nginx 源码一起编译，走的是“源码级集成”路径。只要依赖装对、目录结构清晰、config 文件写准，一个最简模块几分钟就能跑起来。

必备依赖与工具链

不需要额外安装 Nginx 二进制包，而是从源码开始构建。关键依赖只有四类：

• 编译器与基础工具：gcc、g++、make（Ubuntu/Debian 下用 build-essential 一键安装）
• 正则支持库：PCRE 及其开发头文件（libpcre3-dev），Nginx 的 location 匹配、rewrite 等都靠它
• 压缩支持库：zlib 及其开发头文件（zlib1g-dev），用于 gzip、deflate 等响应压缩功能
• SSL 支持（可选但推荐）：openssl 和 libssl-dev，尤其当你模块涉及 HTTPS 处理或需调用 SSL 相关 API 时

Nginx 源码准备与版本选择

模块必须与 Nginx 源码版本兼容。不建议用系统包管理器安装的预编译版 Nginx，因为缺少头文件和构建脚本。

• 从 nginx.org 官网 下载稳定版源码（如 nginx-1.25.4.tar.gz），解压后进入目录
• 若需对接特定生态（如 NGINX Ingress Controller），应克隆对应仓库并 checkout 明确 release 分支（例如 release-1.21.0）
• 确认源码根目录下存在 auto/、src/、configure 等关键路径，这是可编译的前提

模块工程结构与 config 文件

模块不能独立编译，必须被 Nginx 构建系统识别。标准做法是新建一个独立目录（如 my_module/），并在其中提供：

• config：Shell 脚本，告诉 Nginx 构建系统如何引入你的模块。内容通常三行：
  ngx_addon_name=ngx_http_my_module
HTTP_MODULES="$HTTP_MODULES ngx_http_my_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_my_module.c"
• C 源文件（如 ngx_http_my_module.c）：实现 handler、directive、module 结构体等，必须包含 <ngx_config.h> 等头文件
• （可选）头文件：用于跨文件声明，保持接口清晰

编译与加载验证流程

把模块加入 Nginx 编译链，不是插件式加载，而是静态链接进二进制。步骤明确：

• 执行 ./configure --add-module=/path/to/my_module [其它选项]，确保输出中出现 checking for my_module ... found
• 运行 make，成功后检查 objs/nginx 是否生成——这是带模块的新二进制
• 用 ./objs/nginx -t 验证配置语法；再加一条测试 location 和自定义指令，启动后访问看是否生效
• 若报错 “unknown directive”，通常是 config 文件路径错、指令未注册或 nginx.conf 中用了未声明的上下文（如在 http 块里用了只允许在 location 的指令）

不复杂但容易忽略