“符号未找到”本质是运行时链接失败，因模块与Nginx版本、编译参数（如--with-http_ssl_module）、GCC版本或依赖模块顺序不匹配；需用nginx -V确认配置，严格复现编译环境，检查nm -D和ldd -r，并确保load_module顺序满足依赖关系。
动态模块加载时提示“符号未找到”（如 undefined symbol: xxx），本质是模块编译时依赖的函数或变量，在运行时 Nginx 的主程序或已加载的其他模块中找不到对应实现。这不是配置错误，而是链接层面的兼容性或构建问题。
确认模块与 Nginx 版本及编译选项严格匹配
动态模块必须用与当前运行的 Nginx 完全相同的源码、相同的 configure 参数（尤其是 --with-xxx 选项）、相同的 GCC 版本和 C 标准重新编译。哪怕只是 minor 版本不同（如 1.24.0 vs 1.24.1），或主 Nginx 启用了 --with-http_ssl_module 而你编译模块时没加，都可能导致 SSL 相关符号（如 SSL_CTX_set_alpn_select_cb）无法解析。
- 运行
nginx -V查看完整 configure 命令，复制它作为模块编译的基础 - 进入 Nginx 源码目录，执行相同 configure（末尾加
--add-dynamic-module=/path/to/your/module），再make modules - 不要复用为静态编译准备的 obj/ 或 .o 文件；确保 clean 编译环境
检查模块是否隐式依赖其他模块或第三方库
比如某模块调用了 ngx_http_upstream_check_create_peer，但它只在 nginx_upstream_check_module 中定义——若该模块未被加载（或未编译进 nginx），就会报符号缺失。又如使用了 OpenSSL 函数但未正确链接 libssl.so，或链接了错误版本（如系统自带的 1.1.1 与模块编译时的 3.0 不兼容）。
- 用
nm -D your_module.so | grep 'U '查看所有未定义符号（U 表示 undefined） - 对关键符号，用
objdump -T /path/to/nginx | grep symbol_name确认主程序是否导出 - 用
ldd -r your_module.so检查缺失的共享库引用
验证运行时加载顺序与依赖模块是否已就位
Nginx 动态模块按 load_module 指令在配置文件中的出现顺序加载。若模块 A 依赖模块 B 导出的符号，B 必须在 A 之前加载，否则 A 初始化时找不到符号。
- 在
nginx.conf的最顶部（events 块之前）集中声明所有load_module - 确保依赖方模块（如自定义 upstream 模块）排在被依赖方（如 upstream_check 或 http_ssl）之后
- 可临时注释部分模块，逐个启用，定位冲突来源
留意 ABI 变更与宏定义差异
Nginx 内部结构体（如 ngx_http_request_s）字段可能随版本微调；模块若直接访问私有字段或依赖未文档化的宏（如 NGX_HTTP_LAST 在旧版中不存在），也会导致符号解析失败或运行时崩溃。
- 优先使用公开 API（如
ngx_http_get_module_ctx）而非直接操作结构体 - 检查模块源码中是否有条件编译（
#if (NGX_VERSION >= ...)），并确认宏值与当前 Nginx 匹配 - 查看
src/core/ngx_config.h和src/http/ngx_http.h中实际定义的常量和结构
