开发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_moduleHTTP_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 的指令）
不复杂但容易忽略
