学习 Nginx 源码

想学习 Nginx 源码，但作为初学者，直接看源码可能会很懵，所以建议先建立一个整体的框架，再深入细节。整理一个 学习路线图，从环境到源码阅读方法，一步步来。

1. 先对 Nginx 有整体认识

在看源码前，先搞清楚 Nginx 是什么、怎么用、它的核心概念：

• 核心功能：HTTP 服务器、反向代理、负载均衡、缓存等。
• 架构模型：
  • 主进程（Master）：读取配置、管理 Worker。
  • 工作进程（Worker）：处理实际请求，基于事件驱动（epoll /kqueue/select）。
• 模块化：核心模块 + 功能模块（HTTP、Stream、Mail 等）。
• 事件驱动：Nginx 使用异步非阻塞模型，这是它高性能的关键。

建议先看官方文档：https://nginx.org/en/docs/beginners_guide.html

2. 下载并编译源码

# 下载源码
wget http://nginx.org/download/nginx-1.25.3.tar.gz
tar -zxvf nginx-1.25.3.tar.gz
cd nginx-1.25.3

# 查看编译选项
./configure --help

# 最小化编译
./configure --with-debug
make
sudo make install

编译时加 --with-debug 方便调试。

3. 找到入口函数

Nginx 的入口在 src/core/nginx.c 文件的 main() 函数：

int main(int argc, char *const *argv) {
    ngx_debug_init();
    ngx_time_init();
    ngx_log_init(...);
    ngx_init_cycle(...);
    ngx_master_process_cycle(cycle);
}

4. 源码阅读路线（从易到难）

阶段一：理解整体启动流程

• src/core/nginx.c：main() 函数，掌握 Nginx 启动过程。
• src/core/ngx_cycle.c：配置加载与周期管理。
• src/core/ngx_process.c：进程创建与管理。

阶段二：事件驱动模型

• src/event/ngx_event.c
• src/event/modules/ngx_epoll_module.c（Linux 下的事件驱动实现）

阶段三：HTTP 请求处理

• src/http/ngx_http.c：HTTP 框架入口。
• src/http/ngx_http_request.c：请求处理主流程。
• src/http/ngx_http_parse.c：HTTP 协议解析。

阶段四：模块化机制

• src/core/ngx_module.c
• src/http/modules/ 下的各种模块源码（如 ngx_http_static_module.c 静态文件服务）。

5. 推荐学习顺序

1. 运行 Nginx，改几个配置，观察效果。
2. 读 main() 函数，理解启动流程。
3. 研究 Master / Worker 进程创建逻辑。
4. 看事件驱动模块（epoll）。
5. 跟踪一个 HTTP 请求从进入到响应的全过程。
6. 分析一个具体模块，如静态文件服务模块。

✅ 初学者建议：不要一开始就钻进细节，先抓住大框架，再逐步深入。比如先弄明白 Nginx 启动 → 接收请求 → 处理请求 → 返回响应 的完整链路，再去看事件模型和模块机制。

Nginx 源码学习地图，就能像走路线一样，从入口函数 main() 一路走到 HTTP 请求处理的终点。我会用文字 + 流程图的方式，把关键文件和函数串起来，方便你跟着看源码。

Nginx 源码学习地图（从启动到 HTTP 请求处理）

1. 启动流程

main()  [src/core/nginx.c]
  │
  ├─ ngx_debug_init()        // 调试初始化
  ├─ ngx_time_init()         // 时间初始化
  ├─ ngx_log_init()          // 日志初始化
  ├─ ngx_get_options()       // 解析命令行参数
  ├─ ngx_init_cycle()        // 初始化配置周期（读取 nginx.conf）
  │     └─ ngx_conf_parse()  // 解析配置文件
  │           └─ 各模块的配置解析函数
  │
  └─ ngx_master_process_cycle()  // 进入主进程循环
        ├─ fork worker 进程
        └─ ngx_worker_process_cycle()  // 工作进程事件循环

关键文件：

• src/core/nginx.c —— 入口函数、主进程循环
• src/core/ngx_cycle.c —— 配置加载与周期管理
• src/core/ngx_process.c —— 进程创建与管理

2. 事件驱动模型

Worker 进程启动后，会进入事件循环，等待并处理网络事件。

ngx_worker_process_cycle()
  │
  ├─ ngx_event_module_init()  // 初始化事件模块（epoll/kqueue/select）
  │     └─ ngx_epoll_init()   // Linux 下使用 epoll
  │
  └─ ngx_process_events_and_timers()  // 事件循环
        ├─ ngx_epoll_process_events() // 调用 epoll_wait 获取事件
        ├─ ngx_event_process_posted() // 处理延后的事件
        └─ ngx_event_expire_timers()  // 处理定时器事件

关键文件：

• src/event/ngx_event.c
• src/event/modules/ngx_epoll_module.c（Linux）
• src/event/modules/ngx_kqueue_module.c（FreeBSD/macOS）

3. HTTP 请求处理流程

当事件驱动模块检测到新的网络数据，会交给 HTTP 框架处理。

收到客户端连接
  │
  ├─ ngx_http_init_connection()  // 初始化 HTTP 连接
  │
  ├─ ngx_http_wait_request_handler()  // 等待 HTTP 请求行
  │
  ├─ ngx_http_process_request_line()  // 解析请求行（GET /index.html HTTP/1.1）
  │
  ├─ ngx_http_process_request_headers() // 解析请求头
  │
  ├─ ngx_http_process_request()  // 开始处理请求
  │     └─ 执行 HTTP 各阶段处理器（phase handlers）
  │           ├─ rewrite 阶段
  │           ├─ access 阶段
  │           ├─ content 阶段（调用具体模块，如静态文件服务）
  │           └─ log 阶段
  │
  └─ ngx_http_send_header() / ngx_http_output_filter() // 发送响应

关键文件：

• src/http/ngx_http.c —— HTTP 框架入口
• src/http/ngx_http_request.c —— 请求处理主流程
• src/http/ngx_http_parse.c —— HTTP 协议解析
• src/http/modules/ngx_http_static_module.c —— 静态文件服务模块

4. 模块化架构

Nginx 功能由模块实现，每个模块有自己的配置解析和请求处理函数。

模块注册：ngx_modules[]  [src/core/ngx_modules.c]
  │
  ├─ 核心模块（Core Module）
  ├─ 事件模块（Event Module）
  ├─ HTTP 核心模块（HTTP Core）
  └─ HTTP 功能模块（Static、Proxy、FastCGI、SSL等）

关键文件：

• src/core/ngx_module.c
• src/http/modules/ 下的各种模块源码

学习路径建议

1. 先跑通流程：
   • 编译带 --with-debug 的 Nginx
   • 用 gdb 调试，从 main() 一路 step 到事件循环
2. 抓一个请求：
   • 在 ngx_http_process_request() 打断点
   • 用浏览器访问，跟踪完整处理过程
3. 分析一个模块：
   • 从 ngx_http_static_module.c 入手，理解 content 阶段如何工作
4. 深入事件模型：
   • 看 ngx_epoll_module.c 理解 Nginx 如何高效处理并发

Nginx 源码学习流程图

[ 🟢 启动阶段 ]
main()  src/core/nginx.c
   │
   ├── ngx_debug_init()        // 调试初始化
   ├── ngx_time_init()         // 时间初始化
   ├── ngx_log_init()          // 日志初始化
   ├── ngx_get_options()       // 解析命令行参数
   ├── ngx_init_cycle()        // 初始化配置周期
   │       └── ngx_conf_parse()  // 解析 nginx.conf
   │
   └── ngx_master_process_cycle()  // 主进程循环
           ├── fork worker 进程
           └── ngx_worker_process_cycle()  // 工作进程循环


[ 🔵 事件驱动阶段 ]
ngx_worker_process_cycle()
   │
   ├── ngx_event_module_init()   // 事件模块初始化
   │       └── ngx_epoll_init()  // Linux 下 epoll 初始化
   │
   └── ngx_process_events_and_timers()  // 事件循环
           ├── ngx_epoll_process_events()  // 等待并获取事件
           ├── ngx_event_process_posted()  // 处理延后任务
           └── ngx_event_expire_timers()   // 处理定时器


[ 🟡 HTTP 请求处理阶段 ]
收到新连接
   │
   ├── ngx_http_init_connection()  // 初始化 HTTP 连接
   │
   ├── ngx_http_wait_request_handler()  // 等待请求数据
   │
   ├── ngx_http_process_request_line()  // 解析请求行
   │
   ├── ngx_http_process_request_headers() // 解析请求头
   │
   ├── ngx_http_process_request()  // 处理请求
   │       └── 执行 phase handlers（HTTP 处理阶段）
   │               ├── rewrite 阶段
   │               ├── access 阶段
   │               ├── content 阶段（调用具体模块）
   │               │       ├── ngx_http_static_module.c（静态文件）
   │               │       ├── ngx_http_proxy_module.c（反向代理）
   │               │       └── ...
   │               └── log 阶段
   │
   └── ngx_http_send_header() / ngx_http_output_filter() // 发送响应

颜色说明

• 🟢 绿色：启动阶段（初始化、配置解析、进程创建）
• 🔵 蓝色：事件驱动阶段（epoll/kqueue 等事件模型）
• 🟡 黄色：HTTP 请求处理阶段（从接收到响应的全过程）

推荐学习路径

1. 先掌握绿色部分（启动流程）

   • 文件：src/core/nginx.c、src/core/ngx_cycle.c
   • 目标：理解 Nginx 如何启动和加载配置

2. 再看蓝色部分（事件驱动）

   • 文件：src/event/ngx_event.c、src/event/modules/ngx_epoll_module.c
   • 目标：理解 Nginx 高性能的关键 — 事件模型

3. 最后看黄色部分（HTTP 请求处理）

   • 文件：src/http/ngx_http_request.c、src/http/modules/...
   • 目标：跟踪一个 HTTP 请求从接收到响应的全过程