news 2026/9/10 18:42:18

Kong 如何在 IDE 中用 EmmyLua 打断点调试 Lua 代码

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Kong 如何在 IDE 中用 EmmyLua 打断点调试 Lua 代码

Kong 如何在 IDE 中用 EmmyLua 打断点调试 Lua 代码

【免费下载链接】kong🦍 The API and AI Gateway项目地址: https://gitcode.com/GitHub_Trending/ko/kong

在开发 Kong 插件或阅读 Kong 源码时，光靠日志很难看清请求上下文里的变量。DEVELOPER.md 给出的方案是用 EmmyLua 调试器在 IntelliJ IDEA 或 VSCode 中直接打断点：启动 Kong 时通过KONG_EMMY_DEBUGGER环境变量加载一个 C++ 调试库，IDE 侧由 EmmyLua 插件连接该库，之后就能在 Lua 代码中设置断点、命中后查看变量。该集成在 changelog/3.7.0/kong/feat-emmy-debugger.yml 中被标记为 tech preview（技术预览），Kong Inc. 不为其提供官方支持，属于纯粹的开发期便利功能，Kong 官方明确不对使用该集成产生的后果负责，相关问题应反馈给 EmmyLua 项目。

一、安装 IDE 与 EmmyLua 插件

两条路径任选其一，后续步骤通用。

IntelliJ IDEA 路线

  • 从 JetBrains 官网下载并安装 IntelliJ IDEA。注意 IntelliJ 是商业软件，试用期结束后需要付费许可证。
  • 进入Settings→Plugins→Marketplace，搜索EmmyLua并安装该插件。

VSCode 路线

  • 从 Microsoft 官网下载并安装 VSCode。
  • 进入Settings→Extensions，搜索EmmyLua并安装插件，发布者（publisher）必须是Tangzx，搜索结果中有同名插件时以此区分。

EmmyLua 本身是 IntelliJ IDEA 和 VSCode 的 Lua 语言支持插件，自带调试器支持，这是能够打断点的前提。

二、下载 EmmyLua 调试服务端

IDE 插件不能直接连到 Kong 内部的 Lua 代码，中间需要 EmmyLuaDebugger——一个运行在与 Kong 同一台机器上的独立 C++ 程序，负责在 IDE 调试器和 Kong 中运行的 Lua 代码之间做中介。

从 EmmyLuaDebugger 项目的 GitHub Releases 页面下载 release 包。ZIP 文件里只有一个共享库文件：

  • Linux：emmy_core.so
  • macOS：emmy_core.dylib

把这个文件放到你方便的目录，并记住它的绝对路径——启动 Kong 时要用。

一个 Linux 环境的限制需要注意：GitHub 上发布的预编译二进制定位的是比较新的 GLIBC。如果你的 Linux 发行版较老，可能需要按 EmmyLuaDebugger 源码 说明自行编译，而不是直接用 release 包里的库。

三、带调试器启动 Kong

启用调试器的关键动作只有一个：启动 Kong 前把KONG_EMMY_DEBUGGER设置为调试共享库的绝对路径。同时建议只启动 1 个 worker 进程，因为多 worker 调试需要额外处理（原因见第六节的KONG_EMMY_DEBUGGER_MULTI_WORKER说明）。完整命令：

KONG_EMMY_DEBUGGER=/path/to/emmy_core.so KONG_NGINX_WORKER_PROCESSES=1 kong start

其中/path/to/emmy_core.so需要替换为你在第二节放置库文件的绝对路径，例如你放在/opt/emmy/emmy_core.so，命令就写成KONG_EMMY_DEBUGGER=/opt/emmy/emmy_core.so ...。

Kong 在 init_worker 阶段调用该集成（见 kong/init.lua 中的Kong.init_worker），加载逻辑在 kong/tools/emmy_debugger.lua。启动日志中如果看到下面的 NOTICE（源代码中的日志文本，路径部分随实际环境变化）：

loading EmmyLua debugger /path/to/emmy_core.so EmmyLua debugger loaded, listening on port 9966

说明库已加载、调试端口已监听，可以进入 IDE 操作。如果没加载成功，日志里会给出对应的错误提示，代码中实际会校验四种情况（见 kong/tools/emmy_debugger.lua）：

  • 路径不是绝对路径：KONG_EMMY_DEBUGGER (...) must be an absolute path；
  • 文件不存在：KONG_EMMY_DEBUGGER (...) file not found；
  • 扩展名不是.so（Linux）或.dylib（macOS）：must be a .so (Linux) or .dylib (macOS) file；
  • 当前不是第一个 worker 且未开启多 worker 调试：KONG_EMMY_DEBUGGER is only supported in the first worker process, suggest setting KONG_NGINX_WORKER_PROCESSES to 1。

四、在 IDE 中创建调试配置

IntelliJ IDEA：进入Run→Edit Configurations，点击+新建配置，类型选择Emmy Debugger(NEW)，起一个有辨识度的名字，例如 "Kong Gateway Debug"，点OK保存。

VSCode：进入Run→Add Configuration，选择EmmyLua New Debugger，同样命名为 "Kong Gateway Debug"，保存launch.json。

五、打断点并验证命中

在 IntelliJ 中点击Run→Debug，在 VSCode 中点击Run→Start Debugging，选择刚创建的配置。连接建立后，IDE 顶部的 restart 和 stop 按钮会分别变为实心的绿色和红色——这是文档给出的连接成功标志。

文档建议的第一个验证断点：在runloop/handler.lua中定义的 access 处理函数里打断点（源码位于 kong/runloop/handler.lua，文档原文称其为"全局的 access 函数"），然后向 Gateway 发送一个代理请求。调试器应当停在断点上，此时可以查看请求上下文（request context）里的变量。

六、用环境变量控制调试行为

以下环境变量控制 EmmyLua 调试集成的行为（来自 DEVELOPER.md "Debugging environment variables" 一节）：

变量用途
KONG_EMMY_DEBUGGER调试共享库的路径，必须是绝对路径
KONG_EMMY_DEBUGGER_HOST调试器监听的 IP 地址，默认localhost
KONG_EMMY_DEBUGGER_PORT调试器监听的端口，默认9966
KONG_EMMY_DEBUGGER_WAIT设置后 Kong 会先等待调试器连接再继续启动
KONG_EMMY_DEBUGGER_SOURCE_PATH调试器解析源码位置用的源码路径，默认是当前工作目录
KONG_EMMY_DEBUGGER_MULTI_WORKER设置后每个 worker 进程各启动一个调试器，端口从KONG_EMMY_DEBUGGER_PORT起递增；默认只为 0 号 worker 启动一个调试器

例如想让调试器监听127.0.0.1的19966端口，可以在启动命令中追加这两个变量：

KONG_EMMY_DEBUGGER=/path/to/emmy_core.so \ KONG_EMMY_DEBUGGER_HOST=127.0.0.1 \ KONG_EMMY_DEBUGGER_PORT=19966 \ KONG_NGINX_WORKER_PROCESSES=1 kong start

KONG_EMMY_DEBUGGER_WAIT适合"先启动 Kong，再打开 IDE 连调试"的顺序：启动后 Kong 停在"等待 IDE 连接"的位置，日志会打印waiting for IDE to connect，IDE 连上后再继续，避免请求先于连接到来。

七、调试 busted 测试（可选分支）

如果要调试的不是运行中的 Gateway，而是 busted 测试用例，用BUSTED_EMMY_DEBUGGER环境变量代替KONG_EMMY_DEBUGGER，值同样是调试共享库的路径。注意文档明确说明：启用调试后，busted 启动时始终会等待 IDE 连接，也就是说 IDE 侧必须先建立调试会话，测试才会继续跑。KONG_前缀的其余变量也有对应的BUSTED_前缀版本（如BUSTED_EMMY_DEBUGGER_HOST、BUSTED_EMMY_DEBUGGER_PORT）。

限制与注意事项

  • 该功能是 tech preview，Kong Inc. 目前不提供官方支持（见 changelog/3.7.0/kong/feat-emmy-debugger.yml），加载时 Kong 也会向日志打印一条 WARN，说明此集成仅是开发便利功能，Kong 不背书其使用。
  • 老版本 Linux 的 GLIBC 可能与 release 库不兼容，需要自行编译 EmmyLuaDebugger。
  • 不开启KONG_EMMY_DEBUGGER_MULTI_WORKER时只有第一个 worker 进程支持调试，所以调试场景建议把KONG_NGINX_WORKER_PROCESSES设为 1，这也是第三节命令的默认写法。
  • KONG_EMMY_DEBUGGER必须是绝对路径且文件存在，扩展名必须为.so或.dylib，否则调试器不加载，且日志会按上面列出的错误提示给出原因。

【免费下载链接】kong🦍 The API and AI Gateway项目地址: https://gitcode.com/GitHub_Trending/ko/kong

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/10 18:41:52

Rocky Linux 9仓库配置与优化指南

1. Rocky Linux 9 仓库配置的必要性作为RHEL的替代发行版，Rocky Linux 9继承了企业级Linux的稳定特性。但默认仓库往往无法满足实际需求，特别是在国内网络环境下。我最近在部署Rocky Linux 9时发现，官方仓库的访问速度时快时慢，而…

作者头像 李华
网站建设 2026/9/10 18:40:59

K8s调度器与反亲和：Pod更新如何触发关联Pod迁移

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/10 18:37:25

Android手势识别开发全指南：从基础到高级实现

1. Android手势操作基础解析在移动应用开发领域，手势交互已经成为提升用户体验的关键要素。作为Android开发者，掌握手势识别技术能够让你的应用从"能用"升级到"好用"的层次。不同于简单的点击事件，手势操作允许用户通过更…

作者头像 李华
网站建设 2026/9/10 18:36:38

WebBluetooth技术解析与物联网开发实践

1. WebBluetooth技术概述 WebBluetooth是近年来浏览器技术领域最具突破性的创新之一，它允许网页应用通过标准化API直接与附近的蓝牙低功耗(BLE)设备交互。这项技术彻底改变了传统蓝牙开发需要原生应用的局限，让基于浏览器的物联网解决方案成为可能。 我…

作者头像 李华
网站建设 2026/9/10 18:36:23

Android屏幕显示效果优化：从DPI到帧率全面解析

1. Android屏幕显示效果的核心影响因素解析作为一名在移动端开发领域深耕多年的工程师，我经常遇到各种屏幕显示异常的问题。Android设备的显示效果实际上是由硬件参数、系统配置和软件实现共同决定的复杂系统。通过分析热词数据和实际项目经验，我总结出影…

作者头像 李华
网站建设 2026/9/10 18:36:01

croc 如何部署加密存储传输服务并配置下载与过期策略？

croc 如何部署加密存储传输服务并配置下载与过期策略？ 【免费下载链接】croc Easily and securely send things from one computer to another :crocodile: :package: 项目地址: https://gitcode.com/GitHub_Trending/cr/croc 本文解决的任务是：在…

作者头像 李华