Nginx基础教程（23）Nginx开发综述之最简单的模块：给Nginx造个轮子：手把手教你编写第一个模块

原创于 2025-11-28 08:29:33 发布 · 79 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #运维

Nginx基础教程专栏收录该内容

30 篇文章

订阅专栏

一行行代码，让Nginx听你指挥

还记得第一次在服务器上配置Nginx时的成就感吗？那个轻量级、高性能的Web服务器如今已成为全球众多网站的基础设施。但你可能不知道，除了配置，你还可以通过开发自定义模块来扩展Nginx的能力。

Nginx模块开发，听起来高大上，实则就像给Nginx造个小轮子，让它按照你的想法跑起来。今天，就让我们一起揭开Nginx模块开发的神秘面纱，从零开始打造最简单的"Hello World"模块。

前言：为什么需要自定义Nginx模块？

Nginx已经如此强大，为什么还要自己开发模块？想象一下，当现有的功能无法满足你的业务需求，比如你想在响应头中自动添加版权信息、根据特定参数过滤内容，或者实现复杂的访问控制逻辑，这时候自定义模块就派上用场了。

Nginx的模块化架构使其具备了惊人的扩展性。从简单的内容处理到复杂的负载均衡算法，都可以通过模块来实现。正如Nginx官方文档所指出的，Nginx的代码具有高度模块化的特性。

虽然OpenResty和njs模块允许使用Lua或JavaScript扩展Nginx，但有时我们需要更深度的控制和更高的性能，这时候C模块开发就是唯一的选择。

别担心，跟着本文一步步操作，你会发现开发Nginx模块并没有想象中复杂。

第一章：准备工作与环境搭建

1.1 初识Nginx模块类型

在Nginx的世界里，模块分为多种类型，每种类型负责不同的功能：

核心模块：提供Nginx基本功能和基础架构
事件模块：处理事件驱动模型和不同的IO复用
HTTP模块：处理HTTP请求和响应——这是我们今天重点关注的
邮件模块：邮件代理服务
流模块：实现TCP/UDP代理

我们的第一个模块将是HTTP模块，因为它最常见也最实用。

1.2 搭建开发环境

首先，我们需要一个Linux环境（推荐Ubuntu或CentOS）和Nginx源码。假设我们使用Ubuntu，下面是环境搭建步骤：

# 安装依赖包
sudo apt-get update
sudo apt-get install build-essential libpcre3-dev zlib1g-dev -y

# 获取Nginx源码（这里以1.14.0版本为例）
git clone -b release-1.14.0 --depth 1 https://github.com/nginx/nginx.git

# 进入目录并编译
cd nginx
auto/configure && make

如果一切顺利，运行objs/nginx -v应该会显示nginx版本信息。

简单了解一下Nginx的代码结构：

auto/ — 构建脚本
src/ — 源代码

- core/ — 核心代码（基本类型、函数、数据结构等）
- event/ — 事件驱动模型
- http/ — HTTP服务器和模块代码
- os/ — 平台相关代码

现在，我们的基础环境已经准备好了！

第二章：创建最简单的Nginx模块

2.1 模块的基本骨架

让我们从创建一个最简单的"空模块"开始。这个模块暂时什么都不做，但它是我们后续开发的基础。

首先，在Nginx源码目录旁边创建我们的模块目录：

nginx/               # Nginx源码目录
nginx-hello-module/  # 我们的模块目录
├── config           # 模块配置文件
└── hello_module.c   # 模块源码文件

2.2 模块配置文件

config文件是模块的"身份证"，它告诉Nginx构建系统如何编译我们的模块：

# vim: set ft=sh et:
ngx_addon_name=ngx_http_hello_module

ngx_module_type=HTTP
ngx_module_name="$ngx_addon_name"
ngx_module_srcs="$ngx_addon_dir/hello_module.c"

. auto/module

这个配置文件定义了模块的名称、类型和源文件。

2.3 模块源码文件

接下来是真正的代码部分。创建hello_module.c文件：

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>

/* 声明模块上下文 */
static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                              /* preconfiguration */
    NULL,                              /* postconfiguration */
    NULL,                              /* create main configuration */
    NULL,                              /* init main configuration */
    NULL,                              /* create server configuration */
    NULL,                              /* merge server configuration */
    NULL,                              /* create location configuration */
    NULL                               /* merge location configuration */
};

/* 模块指令定义 */
static ngx_command_t ngx_http_hello_commands[] = {
    ngx_null_command  /* 指令结束标记 */
};

/* 模块定义 */
ngx_module_t ngx_http_hello_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_module_ctx,        /* module context */
    ngx_http_hello_commands,           /* module directives */
    NGX_HTTP_MODULE,                   /* module type */
    NULL,                              /* init master */
    NULL,                              /* init module */
    NULL,                              /* init process */
    NULL,                              /* init thread */
    NULL,                              /* exit thread */
    NULL,                              /* exit process */
    NULL,                              /* exit master */
    NGX_MODULE_V1_PADDING
};

这个简单的模块目前什么都不做，但它是一个合法的Nginx模块。

代码要点解析：

每个Nginx模块必须包含三个头文件：ngx_config.h、ngx_core.h和ngx_http.h
ngx_http_hello_module_ctx是模块的上下文结构，包含各种钩子函数
ngx_http_hello_commands数组定义模块支持的配置指令
ngx_http_hello_module是模块的主结构，Nginx通过它识别和加载模块

2.4 编译和加载模块

现在我们可以编译模块了。在Nginx源码目录下执行：

auto/configure --add-dynamic-module=../nginx-hello-module/
make modules

如果一切顺利，会在objs/目录下生成ngx_http_hello_module.so文件，这就是编译好的动态模块。

要使用这个模块，我们需要在Nginx配置文件中加载它：

load_module modules/ngx_http_hello_module.so;

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;
        server_name localhost;
        
        # 这里以后可以添加使用我们模块的配置指令
    }
}

现在，虽然我们的模块还没有任何实际功能，但它已经可以正常加载和运行了！

第三章：让模块真正"做点事"——Hello World

3.1 添加配置指令

一个什么都不做的模块显然不能满足我们，让我们给它添加一个简单的功能：当访问指定位置时，返回"Hello, Nginx Module!"。

首先，我们需要在模块中添加一个配置指令。修改ngx_http_hello_commands数组：

static ngx_command_t ngx_http_hello_commands[] = {
    {
        ngx_string("hello_world"),           /* 指令名称 */
        NGX_HTTP_LOC_CONF | NGX_CONF_NOARGS, /* 使用位置和参数限制 */
        ngx_http_hello_handler,              /* 处理函数 */
        0,                                   /* 配置文件偏移量 */
        0,                                   /* 配置结构偏移量 */
        NULL                                 /* 其他 */
    },
    ngx_null_command  /* 指令结束标记 */
};

这段代码定义了一个名为hello_world的配置指令，当它在Nginx配置中出现时，会调用ngx_http_hello_handler函数。

3.2 实现请求处理函数

现在我们需要实现ngx_http_hello_handler函数：

static ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
    ngx_int_t    rc;
    ngx_buf_t   *b;
    ngx_chain_t  out;
    
    /* 设置响应头 */
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = sizeof("Hello, Nginx Module!") - 1;
    
    /* 设置Content-Type */
    ngx_str_set(&r->headers_out.content_type, "text/plain");
    
    /* 发送响应头 */
    rc = ngx_http_send_header(r);
    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }
    
    /* 分配缓冲区 */
    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));
    if (b == NULL) {
        return NGX_ERROR;
    }
    
    /* 设置响应体 */
    out.buf = b;
    out.next = NULL;
    
    b->pos = (u_char *) "Hello, Nginx Module!";
    b->last = b->pos + sizeof("Hello, Nginx Module!") - 1;
    b->memory = 1;    /* 表明此缓冲区在内存中 */
    b->last_buf = 1;  /* 表明这是最后一个缓冲区 */
    
    /* 发送响应体 */
    return ngx_http_output_filter(r, &out);
}

这个处理函数完成了以下工作：

设置HTTP响应状态码为200
设置Content-Type为text/plain
设置内容长度
创建包含"Hello, Nginx Module!"的缓冲区
发送响应给客户端

3.3 注册处理函数

我们还需要在模块上下文中注册处理函数。修改模块上下文部分：

static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                              /* preconfiguration */
    NULL,                              /* postconfiguration */
    NULL,                              /* create main configuration */
    NULL,                              /* init main configuration */
    NULL,                              /* create server configuration */
    NULL,                              /* merge server configuration */
    NULL,                              /* create location configuration */
    NULL                               /* merge location configuration */
};

对于这个简单示例，我们暂时不需要实现这些钩子函数。

3.4 测试我们的Hello World模块

重新编译模块：

make modules

更新Nginx配置文件以使用我们的新功能：

load_module modules/ngx_http_hello_module.so;

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;
        server_name localhost;
        
        location /hello {
            hello_world;  /* 使用我们模块的指令 */
        }
    }
}

重启Nginx并访问http://localhost:8080/hello，你应该能看到"Hello, Nginx Module!"的响应！

第四章：理解Nginx模块开发的关键概念

4.1 Nginx的内存管理

在Nginx模块开发中，我们使用Nginx自己的内存分配函数，而不是标准的malloc/free：

ngx_palloc(): 从内存池分配内存
ngx_pcalloc(): 从内存池分配并清零内存
ngx_pfree(): 释放内存（仅适用于特定情况）

Nginx使用内存池来管理内存，这意味着在请求结束时，相关内存会自动释放，大大减少了内存泄漏的可能性。

4.2 字符串处理

Nginx定义了自己的字符串类型：

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

与C字符串不同，ngx_str_t不依赖NULL终止符，而是通过len字段确定长度。Nginx提供了一系列字符串处理函数，如ngx_strcmp(), ngx_strcpy(), ngx_strlen()等。

4.3 错误处理

Nginx使用统一的返回码系统：

NGX_OK: 操作成功
NGX_ERROR: 操作失败
NGX_AGAIN: 操作未完成，需要再次调用
NGX_DECLINED: 操作被拒绝（非错误）
NGX_BUSY: 资源不可用
NGX_DONE: 操作完成或在其他地方继续
NGX_ABORT: 函数被中止（替代错误代码）

在我们的处理函数中，需要妥善处理这些返回码，确保Nginx能够稳定运行。

第五章：调试技巧与常见问题

5.1 日志记录

在开发过程中，日志是我们的好朋友。Nginx提供了强大的日志功能：

ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, "This is an error message");
ngx_log_debug0(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "This is a debug message");

日志级别从高到低包括：

NGX_LOG_EMERG
NGX_LOG_ALERT
NGX_LOG_CRIT
NGX_LOG_ERR
NGX_LOG_WARN
NGX_LOG_NOTICE
NGX_LOG_INFO
NGX_LOG_DEBUG

5.2 常见编译问题

模块找不到：确保config文件路径正确，并且使用正确的--add-dynamic-module或--add-module参数
API版本不匹配：确保模块编译时使用的Nginx版本与运行时相同
头文件找不到：确保包含了必要的头文件

5.3 配置指令权限

在定义配置指令时，需要指定指令可以出现的上下文：

NGX_HTTP_MAIN_CONF: 主配置上下文
NGX_HTTP_SRV_CONF: server配置上下文
NGX_HTTP_LOC_CONF: location配置上下文
NGX_HTTP_UPS_CONF: upstream配置上下文
NGX_CONF_FLAG: 指令接受布尔值参数
NGX_CONF_TAKE1: 指令接受一个参数

第六章：从简单到实用——模块进阶思路

我们的Hello World模块虽然简单，但已经包含了Nginx模块开发的所有基本要素。在此基础上，你可以开发更复杂的模块：

6.1 添加配置结构

对于需要存储配置信息的模块，可以创建配置结构：

typedef struct {
    ngx_str_t greeting_message;
    ngx_int_t repeat_count;
} ngx_http_hello_loc_conf_t;

然后在模块上下文中实现创建和合并配置的函数。

6.2 处理请求参数

通过解析请求URI和参数，可以实现更动态的行为：

ngx_str_t uri = r->uri;
ngx_str_t args = r->args;

6.3 访问上游服务

Nginx的 upstream 机制允许模块与后端服务通信，这对于实现反向代理、负载均衡等功能非常有用。

6.4 编写过滤模块

除了处理模块，你还可以编写过滤模块来修改响应内容。过滤模块可以操作HTTP响应头和体，实现如内容替换、添加页脚等功能。

结语：小模块，大世界

恭喜你！你已经成功创建了第一个Nginx模块，并了解了Nginx模块开发的基本知识。从最初的空模块到能够响应请求的Hello World模块，你已经踏入了Nginx扩展开发的世界。

Nginx模块开发是一个深入的过程，今天我们所覆盖的只是最基础的部分。但正如建造高楼需要坚实的地基，这个简单的模块为你后续探索更复杂的开发奠定了坚实的基础。

当你熟悉了基础模式后，可以进一步研究：

读取和修改请求头：实现身份验证、访问控制等功能
生成动态内容：创建完整的处理程序，替代传统CGI程序
实现过滤链：操作响应内容，如HTML页面重写
与外部服务通信：实现与数据库、缓存等的交互
编写负载均衡算法：自定义upstream模块

Nginx的模块化架构是其强大性能和高扩展性的基石。通过自定义模块，你可以让Nginx做几乎任何你想做的事情。记住，每个强大的Nginx功能背后，都有一个或多个模块在默默工作。

开发Nginx模块不仅是扩展功能的手段，更是深入理解Nginx工作原理的途径。当你看着自己编写的模块高效处理着成千上万的请求时，那种成就感绝对值得你的付出！