跳转至

core: 基于 FFI 的 lua-nginx-module 新 API

安装

如果您还没有设置 RPM 仓库订阅，请 注册。然后您可以继续以下步骤。

CentOS/RHEL 7 或 Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-core

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-core

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-core v0.1.32.post1，于 2025 年 12 月 13 日发布。

自 OpenResty 1.15.8.1 起，此库默认自动加载。可以通过 lua_load_resty_core 指令禁用此行为，但请注意，强烈建议使用此库，因为其 FFI 实现比 ngx_lua 模块的 Lua C API 更快、更安全且更完整。

如果您使用的是旧版本的 OpenResty，则必须按如下方式加载此库：

    # nginx.conf

    http {
        # 当您使用 OpenResty 包 1.4.3.9+ 时，您不需要配置以下行。
        init_by_lua_block {
            require "resty.core"
            collectgarbage("collect")  -- 仅用于收集任何垃圾
        }

        ...
    }

描述

此纯 Lua 库使用 LuaJIT FFI 重新实现了 ngx_lua 模块的部分 Nginx API for Lua，并将新的基于 FFI 的 Lua API 安装到 ngx. 和 ndk. 命名空间中，这些命名空间由 ngx_lua 模块使用。

此外，此 Lua 库还将 ngx_lua 模块的任何重要新 Lua API 实现为适当的 Lua 模块，如 ngx.semaphore 和 ngx.balancer。

基于 FFI 的 Lua API 可以与 LuaJIT 的 JIT 编译器一起使用。ngx_lua 的默认 API 基于标准 Lua C API，这将永远不会被 JIT 编译，用户的 Lua 代码始终是解释执行的（速度较慢）。

对新的 ngx_stream_lua_module 的支持也已开始。

此库默认与 OpenResty 包一起提供。因此，您不需要担心依赖关系和要求。

先决条件

警告 此库包含在每个 OpenResty 版本中。您应使用特定 OpenResty 版本中捆绑的此库版本。否则，您可能会遇到严重的兼容性问题。

实现的 API

resty.core.hash

resty.core.base64

resty.core.uri

resty.core.regex

resty.core.exit

resty.core.shdict

resty.core.var

resty.core.ctx

get_ctx_table

语法: ctx = resty.core.ctx.get_ctx_table(ctx?)

类似于 ngx.ctx，但它接受一个可选的 ctx 参数。当 ctx 表不存在时，它将使用调用者的 ctx，而不是创建一个新表。

注意：ctx 表将在当前请求的整个生命周期中使用。在您尝试重用 ctx 表时，请非常小心。您需要确保在当前请求中没有 Lua 代码使用或将要使用 ctx 表，然后再在其他地方重用 ctx 表。

resty.core.request

resty.core.response

resty.core.misc

resty.core.time

resty.core.worker

resty.core.phase

resty.core.ndk

resty.core.socket

resty.core.param

ngx.semaphore

此 Lua 模块实现了用于高效“轻线程”同步的信号量 API，可以跨不同请求工作（但不能跨 nginx 工作进程）。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.balancer

此 Lua 模块实现了在 Lua 中定义动态上游负载均衡器的功能。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.ssl

此 Lua 模块提供了一个 Lua API，用于控制 NGINX 下游 SSL 握手中的 SSL 证书、私钥、SSL 协议版本等。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.ssl.clienthello

此 Lua 模块提供了一个 Lua API，用于对 NGINX 下游 SSL 连接的 SSL 客户端 hello 消息进行后处理。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.ssl.session

此 Lua 模块提供了一个 Lua API，用于操作 NGINX 下游 SSL 连接的 SSL 会话数据和 ID。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.re

此 Lua 模块提供了一个 Lua API，实现了 ngx.re API 的便利工具。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.resp

此 Lua 模块提供了可以用于处理 HTTP 响应的 Lua API。

有关此 Lua 模块的更多详细信息，请参见 文档。

ngx.pipe

此模块提供了一个 Lua API，用于生成进程并以非阻塞方式与其通信。

有关此 Lua 模块的更多详细信息，请参见 文档。

此模块首次在 lua-resty-core v0.1.16 中引入。

ngx.process

此 Lua 模块用于在 Lua 中管理 nginx 进程。

有关此 Lua 模块的更多详细信息，请参见 文档。

此模块首次在 lua-resty-core v0.1.12 中引入。

ngx.errlog

此 Lua 模块提供了 Lua API 用于捕获和管理 nginx 错误日志消息。

有关此 Lua 模块的更多详细信息，请参见 文档。

此模块首次在 lua-resty-core v0.1.12 中引入。

ngx.base64

此 Lua 模块提供了 Lua API 用于 urlsafe base64 编码/解码。

有关此 Lua 模块的更多详细信息，请参见 文档。

此模块首次在 lua-resty-core v0.1.14 中引入。

注意事项

如果用户的 Lua 代码没有被 JIT 编译，则使用此库可能会导致解释模式下性能下降。您只有在用户的 Lua 代码的良好部分被 JIT 编译时才能观察到加速效果。

另见

GitHub

您可以在 nginx-module-core 的 GitHub 仓库 中找到此模块的其他配置提示和文档。