API 网关
API 网关
文档指南
请输入
- 文档首页
API 网关用户指南插件中心自定义插件创建 Lua 插件
复制全文
下载 pdf创建 Lua 插件
文档反馈
问问助手通过自定义 Lua 插件，您可以实现请求头修改、响应体处理、日志输出、流量标记等定制化功能，无需编译和上传二进制文件，即可快速完成轻量级业务扩展。本文介绍如何创建 Lua 插件。
说明
【邀测·申请试用】：该功能目前处于邀测阶段，如需使用，请联系您的客户经理。
背景信息
Lua 是一种轻量级、高效的嵌入式脚本语言，广泛应用于网关代理扩展开发领域。Lua 插件通过 Envoy 原生的机制，允许您在请求和响应的处理链路中插入自定义逻辑。Lua 插件具有以下特点：
- 开发简单：无需 SDK 依赖，直接参考 Envoy Lua Filter API 即可编写脚本，详情请参见 Lua。
- 部署快捷：在控制台直接输入 Lua 代码，无需编译构建流程。
- 热更新：插件配置变更后即时生效，无需重启网关实例。
使用限制
- 仅标准型网关实例支持创建 Lua 插件，弹性网关和 Serverless 网关不支持该能力。
- Lua 插件当前仅支持路由级别配置。
- 自定义插件能力需要网关为 4.3.7 及以上版本。
前提条件
- 已创建标准型网关实例，详情请参见 创建实例。
- 已创建服务，详情请参见 创建服务。
- 已创建路由，详情请参见 创建路由。
操作步骤
步骤一：安装 Lua 自定义插件
- 登录 API 网关控制台。
- 在顶部导航栏，选择目标地域。
- 在左侧导航栏 实例管理 下拉框中选择目标实例后，单击 插件中心。
- 在 插件中心 页面，选择 自定义插件 > 安装自定义插件 ，配置自定义插件的参数。
- 配置项说明插件标识（Key）自定义插件的标识。插件别名配置插件的别名，配置后自定义插件将显示为该名称。资源类型选择 LUA。Lua 脚本在脚本编辑器中输入 Lua 脚本。代码中必须实现 envoy_on_request 或 envoy_on_response 函数。版本插件版本号，默认值为 1.0.0。后续功能迭代时可递增版本号。版本说明当前插件版本的变更说明。
- 单击 确定，完成配置。
步骤二：创建插件
- 在 自定义插件 页面，单击 创建插件。
- 在创建插件页面，配置以下插件参数。
- 配置项说明生效级别插件的生效级别，仅支持路由级别。所属服务在下拉菜单中选择插件所属服务。所属路由在下拉菜单中选择插件所属路由。插件配置配置自定义插件的生效逻辑。支持 JSON 和 YAML 进行配置。
- 单击 确定，完成配置。
结果验证
支持查看插件的信息及状态等内容，创建完成后插件默认为已启用。
Lua 开发指南
Lua 插件示例
脚本结构
Lua 插件通过实现以下两个入口函数与 Envoy 交互：
- envoy_on_request(request_handle)：在请求路径上调用，用于处理入站请求。
- envoy_on_response(response_handle)：在响应路径上调用，用于处理出站响应。
代码示例
以下示例为一个基础的 Lua 插件，功能为将请求体和响应体的大小分别添加到请求头和响应头中，并删除响应中名为foo的头部。
Lua 插件配置示例
以下示例使用 JSON 为例，示例配置包含三条数据映射规则，支持从指定字段或请求体 JSON 路径提取数据，可对源值进行 Base64 解码处理后，分别写入 HTTP 请求头与请求体指定 JSON 节点，实现网关转发时请求头、请求体参数的跨位置拷贝与数据解码转换。
最近更新时间：2026.08.06 14:06:38
这个页面对您有帮助吗？
有用
有用
无用
无用