全局 Lua 模块

在用 Edgelang 编写自定义的 Edge 规则时，有时会需要调用自定义的 Lua 模块，此时可以通过在 全局 Lua 模块 中增加此 Lua 模块。

# 1. 创建全局 Lua 模块

下面我们看下如何创建一个全局 Lua 模块，并在 Edgelang 中引用它。

首先点击 全局配置：

然后点击左侧导航栏的 全局 Lua 模块 进入全局 Lua 模块页面。

在这个页面中，会列出已经存在的全局 Lua 模块，点击 新建 Lua 模块 按钮创建一个新模块。

弹出的 新建 Lua 模块 对话框中提供以下配置项：

• 模块名称：填写模块名称，即后续在 Edgelang 中引用时使用的名称。
• 上传 Lua 文件：点击 选择文件 直接导入已有的 .lua 文件，模块名称默认使用文件名。
• Lua 代码：在编辑框中直接编写 Lua 代码，支持开启 Vim 模式 进行编辑。
• 启动时运行：开启后，Edge Node 启动时会在每个 worker 进程初始化时调用该模块的 init_worker() 函数。注意：启用后，修改该 Lua 模块配置将触发 Edge Node 的优雅重启。此选项于 26.6.1-1 版本首次引入。

例如，编写一个简单的返回问候语的模块：

local _M = {}
function _M.say_hello()
    return "hello world!"
end

return _M

填写完毕后点击 保存 按钮进行保存，Lua 模块会自动下发到每个节点，之后即可在 Edgelang 代码中引用：

true =>
    say(foreign-call(module: "custom_lua_module", func: "say_hello"));

# 2. 同步选项

页面右上方是 同步选项，含义同 全局配置

有点区别的是，当取消选中 自动同步到其他分区 后，全局 Lua 模块除了支持复制所有 Lua 模块到指定分区外，还支持单独复制某一个 Lua 模块到指定分区，让我们点击复制按钮。

然后选择要同步的分区，点击 copy，当前分区的配置就会覆盖指定分区的配置。

# 3. 修改历史

可以在发布页面查看同一个分区下 Lua 模块的修改历史。让我们点击 发布 按钮

找到对应的发布历史，点击 查看详情

就能看到此次的修改内容

# 4. 搜索 Lua 模块

使用 全局 Lua 模块 页面中的搜索框筛选当前页面。搜索会同时匹配模块名称和 Lua 代码。

在 Windows 或 Linux 上按 Ctrl+K，在 macOS 上按 Cmd+K，可以打开全局搜索。 全局 Lua 模块搜索结果会显示所属分区，用于区分同名模块。后端搜索还支持分页和分区筛选。

# 5. 自定义共享内存字典

全局 Lua 模块 页面的 自定义共享内存字典 标签页用于为网关节点定义共享内存字典。每个字典会在网关节点上生成一个指定名称和大小的 nginx lua_shared_dict 共享内存区，同一网关节点的所有 worker 进程共享其中的数据。Lua 代码（例如全局 Lua 模块）通过 ngx.shared.<name> 访问字典。示例请参阅自定义挑战，其中的 Lua 模块把验证码答案存储在 ngx.shared.captcha_store 中。

点击 新建自定义共享内存字典，填写字典的 名字 和 大小，然后点击 保存。在列表中点击 编辑 或 删除 可以修改或删除字典。变更保存后立即生效，无需发布，并会触发网关进程更新（binary upgrade），重启 Edge Node 进程。详见配置变更与进程更新。

删除字典前，请确认没有已发布的 Lua 模块继续引用它，否则相关请求会在运行时访问不到共享内存。

共享内存字典按分区配置。Lua 模块 和 自定义共享内存字典 两个标签页共用右上方的分区选择框，以及同一个 自动同步到其他分区 选项。选择 default 分区时可以修改该选项：

• 开启该选项时，只能编辑 default 分区，在该分区保存的字典会替换其他所有分区的字典。
• 关闭该选项时，每个分区各自保存字典。两个标签页分别提供 复制到其他分区：Lua 模块 标签页复制 Lua 模块，自定义共享内存字典 标签页复制字典定义。

开启该选项本身不会复制任何字典。其他分区会在 default 分区下一次保存或删除字典时获得这些字典。在此之前，同步到其他分区的 Lua 模块无法使用只存在于 default 分区的字典。如需立即复制，在 default 分区中点击任一字典的 编辑，不做修改直接点击 保存。

# 复制自定义共享内存字典

在 default 分区关闭 自动同步到其他分区，然后选择源分区，切换到 自定义共享内存字典 标签页，点击 复制到其他分区。

在弹出的 Copy Custom Shared Memory Dictionaries 窗口中勾选目标分区，点击 复制。源分区不能作为目标分区。

复制前请确认以下覆盖范围：

• 复制源分区的全部已保存字典定义，整组替换每个目标分区的字典定义。
• 仅存在于目标分区的字典定义会被删除。源分区没有字典时，会清空目标分区的全部字典定义。
• 不复制字典中的运行数据，也不复制 Lua 模块。

复制成功后立即下发有变更的目标分区，无需另行发布。如果源分区或任一目标分区还有未发布的 通用 配置变更，或正在批量发布，复制会失败。请先完成发布，再重试复制。保存字典时，所作用的任一分区有未发布的 通用 配置变更，也会导致保存失败。

修改共享内存字典需要 全局 Lua 模块 的写权限，通过 API 路径 partitions/{partition_id}/ngx 保存时还需要 通用 的写权限。更早的版本只需要 通用 的写权限，因此升级后请为管理共享内存字典的用户组授予 全局 Lua 模块 的写权限。

按分区配置共享内存字典在 OpenResty Edge 26.12.1-1 中首次引入。在更早的版本中，所有分区共用同一个字典列表。

# 6. 模块变量与更新

从 OpenResty Edge 26.12.1-1 开始，每个全局 Lua 模块的每个版本都有独立的变量环境。 模块中的非 local 赋值不会覆盖另一个模块的同名变量；同一版本再次执行时可保留这些值， 新版本则使用新的环境，避免旧版本的初始化标志或全局变量残留。

请通过模块返回的接口和 require 显式共享数据，不要依赖不同模块之间的隐式全局变量共享。 这种环境隔离不等同于安全沙箱，也不应当用于跨 worker 的持久化存储。

重新执行模块时，会根据当前版本的 require 调用重新建立依赖关系。 新版本不再引用的旧依赖不会继续影响它的更新；多个模块仍在使用的依赖会保留。