nginx 1.31.5正式发布：控制 API、谓词 Location 与 JSON 模块三大能力全面解读

2026 年 9 月 3 日，nginx 1.31.5 主线版本正式发布。

本次版本更新围绕配置与控制能力、请求体处理、JSON 解析、协议与模块兼容性、内存与边界安全、Windows 构建依赖等多个方向展开。其中，最值得关注的变化包括：NGINX Control API、Predicate Locations、ngx_http_json_module，以及新增的 client_body_early_read 指令。

从发布内容来看，nginx 1.31.5 不只是一次常规维护版本更新。它在核心能力层面新增了控制 API 和 JSON 解析相关模块，同时继续完善 FastCGI、uWSGI、Memcached、QUIC、Slice Filter、Event Pipe 等既有模块的边界处理与稳定性表现。

一、nginx 1.31.5 发布信息

nginx 1.31.5 是一个主线版本，发布时间为 2026 年 9 月 3 日。

本次发布包含 21 次提交，共有 9 位贡献者参与，涉及 31 个文件变更。

发布说明中提到，本版本的核心特性包括：

• NGINX Control API

• Predicate Locations

• ngx_http_json_module

• client_body_early_read 指令

• FastCGI 多字节参数名称长度支持

• uWSGI 多字节参数名称长度支持

• JSON 解析器与 JSON unescape 功能

• QUIC 对异常 CRYPTO 帧的处理改进

• Slice Filter 范围请求溢出保护

• Event Pipe 下游缓冲区生命周期修复

• Windows 构建使用的 OpenSSL 与 PCRE 更新

同时，本次更新也修复和优化了多个模块中的边界处理问题，包括 JSON 长度计算溢出检测、Memcached 结束标记处理、核心通道文件描述符错误处理等。

二、最大看点：新增 NGINX Control API

本次 nginx 1.31.5 最受关注的新增能力之一，是 NGINX Control API。

发布记录显示，Control API 在 2026 年 9 月 2 日完成相关提交，并且包含以下三个部分：

• Control API

• Control API reload support

• Control API in memory config dump

从这些更新名称可以看出，Control API 相关能力覆盖了控制接口本身、重载支持以及内存中的配置导出。

其中，reload support 表示 Control API 增加了重载支持。

in memory config dump 则表明 Control API 增加了内存配置导出相关能力。

对于 nginx 而言，配置、重载和运行控制始终是重要组成部分。此次将相关能力以 Control API 的形式纳入版本更新，是 nginx 1.31.5 的重要变化。

在本次发布信息中，Control API 不仅出现在版本摘要中，也在提交记录中以独立功能项连续出现，说明它是本版本的核心更新方向之一。

三、Predicate Locations：Location 能力迎来新增变化

nginx 1.31.5 新增了 Predicate Locations。

Predicate Locations 被列入版本更新摘要，同时也在提交记录中作为独立更新项出现。

Location 是 nginx 配置体系中的重要组成部分。本次新增 Predicate Locations，意味着 nginx 1.31.5 在 Location 相关能力上进行了扩展。

发布信息没有提供具体配置写法、匹配规则、语法格式或使用示例，因此不能对其实际配置方式作额外推断。但可以确认的是，Predicate Locations 是 nginx 1.31.5 中明确列出的新增特性，也是本次发布的重点内容之一。

对于持续关注 nginx 路由、匹配与请求处理能力演进的用户来说，这项更新值得重点关注。

四、新增 ngx_http_json_module：JSON 解析能力进入 nginx

nginx 1.31.5 新增了 JSON 解析器模块，也就是 ngx_http_json_module。

本次与 JSON 相关的变更并不只有一个模块，而是一组连续完善的更新，具体包括：

• 核心新增 JSON unescape 功能

• 核心新增 JSON parser

• JSON parser 允许顶层标量

• 新增 JSON parser module

• 修复 JSON 长度计算中的溢出检测问题

这意味着 nginx 1.31.5 对 JSON 的支持不仅体现在 HTTP 模块层面，也包含核心 JSON 解析能力与转义处理能力。

首先，核心新增了 JSON unescape 功能。

JSON 数据处理中，转义与反转义是基础环节。此次在核心中加入 JSON unescape 功能，为后续 JSON 解析相关能力提供了基础支持。

其次，核心新增了 JSON parser。

JSON parser 的加入是本次版本的关键变化之一。发布记录显示，JSON parser 后续还进行了补充，使其允许顶层标量。

所谓允许顶层标量，意味着 JSON parser 的处理范围进一步扩展。发布说明明确指出，该解析器允许顶层标量，这是本次 JSON parser 的一项单独更新。

随后，nginx 1.31.5 新增了 JSON parser module。

这也是发布摘要中提到的 ngx_http_json_module。该模块的加入，使 JSON 相关能力成为本次主线版本的重要组成部分。

此外，本次版本还修复了 JSON 长度计算中的溢出检测问题。

该修复发生在 2026 年 9 月 1 日，属于 JSON 功能完善过程中的安全性和边界处理改进。长度计算与溢出检测直接关系到解析过程中的边界判断，因此该修复也是 JSON 相关更新中不可忽略的一部分。

综合来看，nginx 1.31.5 的 JSON 更新包含了从基础处理、解析器能力、顶层值支持、HTTP 模块到溢出检测修复的一系列变更：

• 新增 JSON unescape

• 新增 JSON parser

• 支持顶层标量

• 新增 JSON parser module

• 修复长度计算溢出检测

这组更新构成了 nginx 1.31.5 中另一条非常明确的功能主线。

五、新增 client_body_early_read 指令

nginx 1.31.5 新增了 client_body_early_read 指令。

该指令在 2026 年 8 月 21 日被加入，并被列入本次版本发布摘要。

从名称可以确认，该指令与客户端请求体的提前读取有关。

请求体处理是 nginx HTTP 请求处理流程中的重要环节，client_body_early_read 的加入，意味着 nginx 在客户端请求体读取相关控制上新增了一项指令。

本次发布内容没有给出该指令的可用上下文、参数形式、默认行为、配置示例或具体工作流程，因此不应对其配置细节作进一步扩展。但作为 nginx 1.31.5 新增的指令，它是本版本 HTTP 请求体处理方向的重要更新之一。

六、FastCGI 与 uWSGI：支持多字节参数名称长度

在应用协议支持方面，nginx 1.31.5 对 FastCGI 和 uWSGI 进行了同步更新。

本次新增的两项变更分别是：

• FastCGI 支持多字节参数名称长度

• uWSGI 支持多字节参数名称长度

这两项提交均发生在 2026 年 8 月 20 日。

FastCGI 与 uWSGI 都是 nginx 常见的上游通信方式。此次更新聚焦于参数名称长度的多字节支持，属于协议参数处理层面的兼容性增强。

发布摘要明确将这两项内容分别列出，说明 FastCGI 和 uWSGI 的实现均完成了相应调整，而不是仅针对其中某一种协议进行变更。

因此，nginx 1.31.5 在 FastCGI 与 uWSGI 方向上的更新重点可以概括为：支持多字节参数名称长度。

七、核心改进：通道文件描述符接收错误不再致命

nginx 1.31.5 对核心模块进行了改进。

具体变化是：将通道文件描述符接收错误调整为非致命错误。

这项更新发生在 2026 年 8 月 26 日。

发布摘要中描述为：Core make channel file descriptor receive errors non-fatal。

也就是说，核心在处理通道文件描述符接收错误时，不再将这类错误视为致命错误。

这项改动属于核心错误处理策略的调整，是 nginx 1.31.5 稳定性改进的一部分。

同一天，核心还完成了另一项修改：在工作进程关闭时删除 accept timer。

该项提交名称为 Core delete accept timer on worker shutdown。

因此，2026 年 8 月 26 日的核心相关更新包括两部分：

• 通道文件描述符接收错误变为非致命

• 工作进程关闭时删除 accept timer

这两项内容都属于 nginx 核心运行与关闭流程相关的更新。

八、Memcached：最大支持长度处理中遵循结束标记

nginx 1.31.5 对 Memcached 模块进行了调整。

本次更新内容为：在最大支持长度处理中遵循结束标记。

发布摘要中的描述是：Memcached respect the end marker in the maximum supported length。

该更新发生在 2026 年 8 月 26 日。

Memcached 模块此次改动聚焦于最大支持长度与结束标记之间的处理关系。发布说明没有提供更详细的实现逻辑、场景描述或配置层面的变化，因此可以确认的内容是：nginx 1.31.5 已对 Memcached 模块在最大支持长度处理中的结束标记行为进行了修正。

九、QUIC：拒绝在 1-RTT 数据包中接收的 CRYPTO 帧

nginx 1.31.5 对 QUIC 模块进行了更新。

具体内容为：拒绝在 1-RTT 数据包中接收到的 CRYPTO 帧。

该更新发生在 2026 年 8 月 26 日，发布摘要中的描述为：QUIC rejected CRYPTO frames received in 1-RTT packets。

这是 QUIC 协议处理方向的一项明确变更。

本次更新说明中没有展开 CRYPTO 帧处理的完整流程，也没有给出更多协议实现细节。但可以确认，nginx 1.31.5 已增加对这一情形的拒绝处理。

对于使用 QUIC 相关能力的场景，这项更新属于协议帧处理规则方面的改进。

十、Slice Filter：为切片范围请求加入溢出保护

nginx 1.31.5 对 Slice Filter 进行了更新。

本次变化是：为切片范围请求加入溢出保护。

发布摘要描述为：Slice filter overflow protection in slice range requests。

该更新同样发生在 2026 年 8 月 26 日。

Slice Filter 的这项调整聚焦于 slice range requests，也就是切片范围请求中的溢出保护。

溢出保护属于边界处理的重要内容。本次版本在 Slice Filter 中加入该保护，说明 nginx 1.31.5 对切片范围请求相关的数值边界处理进行了完善。

发布信息没有进一步给出触发条件、影响范围或实现细节，因此不对其行为作额外推断。

十一、Event Pipe：不再释放仍被下游使用的缓冲区

nginx 1.31.5 对 Event Pipe 进行了重要修复。

具体变更为：不再释放仍然被下游使用的缓冲区。

发布摘要中的表述是：Event pipe do not free buffers still used by the downstream。

该更新发生在 2026 年 8 月 26 日。

缓冲区生命周期与上下游处理关系，是事件管道处理中的关键问题。此次修复明确指出，仍被下游使用的缓冲区不应被释放。

因此，这项更新属于 Event Pipe 缓冲区管理相关的修复。

从发布摘要可见，这不是新增功能，而是针对下游仍在使用缓冲区这一状态进行的处理修正。该变更是 nginx 1.31.5 在数据传递与缓冲区管理方面的重要稳定性更新。

十二、Windows 构建依赖更新：OpenSSL 与 PCRE 升级

nginx 1.31.5 更新了 Windows 构建所使用的 OpenSSL 与 PCRE。

该项更新发生在 2026 年 9 月 2 日。

发布摘要中的描述为：Updated OpenSSL and PCRE used for win32 builds。

这意味着，本次变更针对的是 win32 构建使用的 OpenSSL 和 PCRE 组件。

需要注意的是，发布信息明确限定了这一更新面向 Windows 构建。因此，本次内容可准确概括为：nginx 1.31.5 更新了 win32 builds 所使用的 OpenSSL 与 PCRE。

十三、按时间线梳理 nginx 1.31.5 的提交内容

为了更清晰地理解本次版本的形成过程，下面按照提交时间进行汇总。

2026 年 8 月 20 日

本次提交包括：

• 版本号更新

• FastCGI 支持多字节参数名称长度

• uWSGI 支持多字节参数名称长度

这一天的更新重点集中在版本准备以及 FastCGI、uWSGI 参数名称长度支持上。

2026 年 8 月 21 日

本次提交包括：

• 新增 client_body_early_read 指令

该指令是 nginx 1.31.5 中请求体处理方向的新增内容。

2026 年 8 月 25 日

本次提交集中在 JSON 能力建设，包括：

• 核心新增 JSON unescape 功能

• 核心新增 JSON parser

• JSON parser 允许顶层标量

• 新增 JSON parser module

这一天构成了 nginx 1.31.5 JSON 相关更新的主体。

2026 年 8 月 26 日

本次提交内容较多，涉及核心、Memcached、QUIC、Slice Filter、Event Pipe 和 Predicate Locations，具体包括：

• 核心将通道文件描述符接收错误调整为非致命

• 核心在工作进程关闭时删除 accept timer

• Memcached 在最大支持长度处理中遵循结束标记

• QUIC 拒绝在 1-RTT 数据包中接收的 CRYPTO 帧

• Slice Filter 为切片范围请求加入溢出保护

• Event Pipe 不释放仍被下游使用的缓冲区

• 新增 Predicate Locations

这也是本次版本中覆盖模块范围最广的一天。

2026 年 9 月 1 日

本次提交包括：

• 修复 JSON 长度计算中的溢出检测问题

这是对前期 JSON 解析能力建设的进一步完善。

2026 年 9 月 2 日

本次提交包括：

• Control API

• Control API 重载支持

• Control API 内存配置导出

• 更新 Windows 构建使用的 OpenSSL 和 PCRE

• nginx 1.31.5 发布版本提交

其中，Control API 及其配套能力是当天最核心的更新内容。

2026 年 9 月 3 日

nginx 1.31.5 主线版本正式发布。

十四、本次版本完整变更清单

下面汇总 nginx 1.31.5 中已明确列出的全部更新内容：

• FastCGI 支持多字节参数名称长度

• uWSGI 支持多字节参数名称长度

• 新增 client_body_early_read 指令

• 新增 JSON unescape 功能

• 新增 JSON parser

• JSON parser 允许顶层标量

• 新增 JSON parser module

• 修复 JSON 长度计算中的溢出检测

• 核心将通道文件描述符接收错误调整为非致命

• 工作进程关闭时删除 accept timer

• Memcached 在最大支持长度处理中遵循结束标记

• QUIC 拒绝在 1-RTT 数据包中接收的 CRYPTO 帧

• Slice Filter 为切片范围请求加入溢出保护

• Event Pipe 不释放仍被下游使用的缓冲区

• 新增 Predicate Locations

• 新增 NGINX Control API

• Control API 支持 reload

• Control API 支持内存配置导出

• 更新 win32 构建使用的 OpenSSL

• 更新 win32 构建使用的 PCRE

• 完成 nginx 1.31.5 发布版本提交

十五、结语

代码地址：github.com/nginx/nginx

nginx 1.31.5 的更新重点非常清晰。

一方面，版本新增了 NGINX Control API、Predicate Locations、ngx_http_json_module、client_body_early_read 等能力；另一方面，也持续完善了 FastCGI、uWSGI、Memcached、QUIC、Slice Filter、Event Pipe 和核心模块的兼容性、错误处理、缓冲区管理与溢出保护。

其中，Control API 的加入，以及 reload support 和 in memory config dump 两项配套能力，是本版本最受关注的更新之一。

与此同时，JSON 相关更新从 unescape、parser、顶层标量支持、parser module 到长度计算溢出检测修复，形成了一条完整而集中的演进路线。

对于关注 nginx 主线版本新特性的用户来说，nginx 1.31.5 值得重点关注的关键词可以概括为：

• Control API

• Predicate Locations

• JSON parser module

• client_body_early_read

• FastCGI 与 uWSGI 多字节参数名称长度

• QUIC CRYPTO 帧处理

• Slice 范围请求溢出保护

• Event Pipe 缓冲区管理

• Windows 构建依赖更新

官方完整变更内容可查看 nginx.org 的 CHANGES 文件。

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。