排查 nginx 模块加载顺序冲突，核心在于理解并控制 `ngx_module_t` 在编译链接时的静态注册顺序。nginx 的模块分为核心、事件、过滤器和上游等类型，其中核心模块（如 `ngx_core_module`）必须在其他所有模块之前初始化，而过滤器模块则依赖其处理链的顺序。当出现配置解析错误或运行时行为异常时，通常是因为某个模块的初始化函数（`init`）或配置合并函数（`merge`）执行时机不对，导致后续模块读取了未就绪的环境变量或错误的默认值。解决此问题的最直接方法是检查编译参数中的模块添加顺序，因为 nginx 严格按照 `--add-module` 或源码中 `objs/makefile` 里定义的顺序来构建全局模块数组 `ngx_modules[]`。
如何确定当前已加载模块的实际顺序
要查看当前 Nginx 实例中模块的加载顺序，可以使用 `nginx -V` 命令查看编译参数，或者通过编写一个简单的测试模块来打印其初始化顺序。更直接的方式是检查 Nginx 启动日志或启用调试模式，观察模块初始化的输出。由于 Nginx 的全局模块数组 `ngx_modules` 是在编译时生成的，因此 `nginx -V` 输出的 `--add-module` 顺序通常反映了模块在数组中的相对位置，但需注意核心模块和内置模块有固定的优先级。对于自定义模块，其顺序完全取决于编译脚本中的定义顺序。
# 假设我们有两个自定义模块：module_a 和 module_b
# 在 Makefile 或 configure 脚本中，它们的添加顺序决定了加载顺序
# 错误示例：如果 module_b 依赖于 module_a 的配置，但先加载了 module_b
./configure --prefix=/usr/local/nginx \
--add-module=/path/to/module_b \
--add-module=/path/to/module_a \
# ... 其他参数
# 正确示例：确保依赖模块在前
./configure --prefix=/usr/local/nginx \
--add-module=/path/to/module_a \
--add-module=/path/to/module_b \
# ... 其他参数
# 验证方法：重新编译后，使用 nginx -V 查看输出顺序
nginx -V
上述代码展示了如何通过调整 `--add-module` 的参数顺序来解决潜在的加载冲突。在编译阶段，Nginx 会将这些模块按顺序添加到 `ngx_modules` 数组中。如果模块 A 依赖于模块 B 提供的某些全局状态或配置上下文，那么模块 A 必须排在模块 B 之后加载。通过修改编译脚本中的顺序，可以强制改变模块的初始化次序。编译完成后，运行 `nginx -V` 可以确认最终的模块列表顺序是否与预期一致。这种方法适用于大多数由编译顺序引起的配置解析问题。
如何处理核心模块与第三方模块的初始化依赖
核心模块（如 `ngx_core_module`）负责解析基本配置指令（如 `worker_processes`、`error_log`），它们必须在任何第三方模块初始化之前完成设置。如果第三方模块试图在核心模块之前访问这些基础配置，会导致空指针或默认值错误。解决这一问题的关键在于理解 Nginx 的模块化架构：核心模块的 ID 是固定的，且始终位于 `ngx_modules` 数组的前部。第三方模块不应假设自己在核心模块之前运行，而应通过正确的钩子函数（hooks）来确保执行顺序。
# 在自定义模块的 ngx_module_t 结构中，可以通过 type 字段指定模块类型
static ngx_uint_t my_module_type = NGX_CORE_MODULE;
// 如果模块需要依赖核心模块的配置，应将其类型设置为 NGX_EVENT_MODULE 或 NGX_HTTP_MODULE
// 并确保在配置合并阶段（merge）正确处理继承关系
// 示例：在模块的 init_main_conf 函数中，安全地获取核心模块配置
static char *ngx_http_my_module_init(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) {
// 获取核心模块的配置上下文
ngx_core_conf_t *ccf = ngx_pget_conf(cf->pool, ngx_get_module_config(cf->cycle->main_conf, ngx_core_module_id));
if (ccf == NULL) {
return "Failed to get core configuration";
}
// 现在可以安全地使用 ccf->worker_processes 等字段
printf("Worker processes: %u\n", ccf->worker_processes);
return NGX_CONF_OK;
}
// 注意：不要尝试在核心模块之前修改核心配置，这会导致未定义行为
这段代码演示了如何在第三方模块中安全地访问核心模块的配置。关键点在于使用 `ngx_get_module_config` 函数来获取特定模块类型的配置结构体，而不是假设配置已经存在。通过这种方式，即使模块加载顺序发生微小变化，只要核心模块已经初始化（这是 Nginx 保证的），第三方模块就能正确获取所需数据。此外，应避免在 `init` 阶段修改核心模块的全局状态，因为这可能影响其他模块的行为。如果确实需要修改，应在 `postconfiguration` 阶段进行，此时所有核心配置都已就绪。
基于 worker_processes 配置的具体问题排查
当 `worker_processes` 配置发生变化时，可能会引发模块加载顺序相关的副作用，特别是对于那些缓存了进程数量或绑定到特定 CPU 核心的模块。例如，某些负载均衡模块或日志轮转模块可能在初始化时记录了当前的 `worker_processes` 值，并在后续操作中硬编码使用该值。如果模块加载顺序不当，导致这些模块在 `worker_processes` 被最终确定之前初始化，它们可能会使用默认值（通常是 1），从而在配置更改后出现行为不一致。
为了解决这个问题，可以在模块的 `postconfiguration` 阶段重新查询 `worker_processes` 的值，而不是在 `init` 阶段缓存它。这样可以确保无论模块加载顺序如何，都能获取到最新的配置值。具体做法是修改模块的初始化逻辑，将依赖 `worker_processes` 的操作推迟到配置解析完成后。同时，建议在模块文档中明确说明其对核心配置的依赖关系，以便维护者了解潜在的顺序敏感性。
