ngx_config.h统一屏蔽系统差异，通过configure生成平台宏、映射类型、封装api，模块须调用nginx跨平台接口并遵循其适配机制验证行为。

在 Nginx 模块开发中，跨平台兼容性不是靠运气实现的，而是由 ngx_config.h 这个头文件统一兜底的。它不提供功能，但决定了模块能否在 Linux、FreeBSD、macOS 甚至 Windows（通过 Cygwin/WSL）上正确编译和运行。

ngx_config.h 的核心作用：屏蔽系统差异

这个头文件本质是一层“系统特征抽象”，在 configure 阶段根据目标平台自动定义宏、重命名函数、补全缺失类型。比如：

• NGX_HAVE_EPOLL 或 NGX_HAVE_KQUEUE 决定事件驱动模型的底层选择
• size_t、off_t、uintptr_t 等类型被统一映射为平台安全的等价类型
• ngx_socket_t 在 Unix 下是 int，在 Windows 下可能被 typedef 为 SOCKET
• 某些系统缺少 strnlen 或 clock_gettime，Nginx 就在 ngx_config.h 中触发 fallback 实现的包含逻辑

模块中如何安全调用系统 API

直接写 epoll_ctl() 或 kqueue() 是危险的。正确做法是依赖 Nginx 封装好的跨平台接口：

• 用 ngx_event_actions 结构体统一调度 I/O 多路复用操作，模块只需调用 ngx_add_event() 而不用关心底层是 epoll 还是 kqueue
• 文件操作优先走 ngx_open_file()、ngx_read_file()，它们内部已处理 O_CLOEXEC、EINTR 重试、Windows 句柄语义等细节
• 时间相关一律用 ngx_timeofday() 或 ngx_clock_gettime()，避免直接调用 gettimeofday() 或 CLOCK_MONOTONIC
• 内存分配必须用 ngx_palloc() / ngx_pcalloc()，而非 malloc()，确保与 Nginx 内存池生命周期一致

自定义系统调用适配的常见陷阱

若模块需引入新系统能力（如 Linux 的 io_uring 或 macOS 的 kevent_qos），不能绕过 ngx_config.h 机制：

• 先在 auto/os/* 下添加探测脚本（如 auto/os/linux 中加 ngx_feature="io_uring"），让 configure 生成对应宏（如 NGX_HAVE_IO_URING）
• 在 src/os/unix/ngx_user.h 或模块私有头中，用 #ifdef NGX_HAVE_IO_URING 包裹条件编译代码
• 避免硬编码系统头文件路径（如 #include <liburing.h></liburing.h>），应通过 auto/lib/uring/conf 统一管理依赖检测与 include 路径
• 系统调用失败时，必须用 ngx_errno（即 errno 或 WSAGetLastError()）判断错误，而不是直接比较 -1

验证跨平台行为的最小实践

写完模块后，仅编译通过远远不够。建议在不同平台做三件事：

• 检查 configure 日志，确认关键特性宏（如 NGX_HAVE_OPENAT）是否按预期启用或禁用
• 用 grep -r "your_module_name" objs/Makefile 确认源文件参与了构建，且未因宏未定义被跳过
• 在目标平台运行 strace -e trace=epoll_wait,kevent,read,write nginx -t（Linux/macOS）或 Process Monitor（Windows），观察实际发出的系统调用是否符合预期