OpenResty ＞ Lua断点调试

OpenResty Lua 代码断点调试

• [OpenResty Lua 代码断点调试指南：VSCode + LuaPanda](#OpenResty Lua 代码断点调试指南：VSCode + LuaPanda)
• • 背景
  • 环境准备
  • [步骤一：安装 VSCode 插件](#步骤一：安装 VSCode 插件)
  • [步骤二：安装 luarocks 和 luasocket](#步骤二：安装 luarocks 和 luasocket)
  • [步骤三：下载 LuaPanda 调试库](#步骤三：下载 LuaPanda 调试库)
  • [步骤四：创建 VSCode 调试配置](#步骤四：创建 VSCode 调试配置)
  • [步骤五：配置 OpenResty](#步骤五：配置 OpenResty)
  • [步骤六：在 Lua 代码中启用调试](#步骤六：在 Lua 代码中启用调试)
  • 步骤七：开始调试
  • 调试功能
  • 常见问题
  • • [1. 报错 "please install luasocket!"](#1. 报错 "please install luasocket!")
    • [2. 断点不命中](#2. 断点不命中)
    • [3. 警告 "writing a global Lua variable ('LuaPanda')"](#3. 警告 "writing a global Lua variable ('LuaPanda')")
  • 生产环境注意事项
  • 总结
  • 参考链接

OpenResty Lua 代码断点调试指南：VSCode + LuaPanda

在 OpenResty 开发中，调试 Lua 代码一直是个痛点。本文将详细介绍如何使用 VSCode + LuaPanda 实现图形化断点调试。

背景

OpenResty 基于 Nginx + LuaJIT，与普通 Lua 环境有所不同：

• 使用 LuaJIT（兼容 Lua 5.1）而非标准 Lua
• 运行在 Nginx worker 进程中
• 有自己的 cosocket 实现

因此，配置调试环境需要一些额外步骤。

环境准备

• macOS（本文基于 macOS，Linux 类似）
• OpenResty 已安装（/usr/local/openresty）
• VSCode
• Homebrew

步骤一：安装 VSCode 插件

在 VSCode 扩展市场搜索并安装 LuaPanda。

步骤二：安装 luarocks 和 luasocket

LuaPanda 依赖 luasocket 进行网络通信。关键点：必须为 LuaJIT 编译 luasocket。

# 安装 luarocks
brew install luarocks

# 为 LuaJIT 编译安装 luasocket（关键步骤！）
luarocks --lua-dir=/usr/local/openresty/luajit --lua-version=5.1 install luasocket

注意 ：直接 luarocks install luasocket 会安装 Lua 5.4 版本，与 OpenResty 的 LuaJIT 不兼容，会报错 please install luasocket!

安装完成后，luasocket 位于 ~/.luarocks/ 目录：

~/.luarocks/
├── share/lua/5.1/
│   ├── socket.lua
│   └── socket/
└── lib/lua/5.1/
    ├── socket/core.so
    └── mime/core.so

步骤三：下载 LuaPanda 调试库

mkdir -p ~/LuaProjects/debugger
curl -o ~/LuaProjects/debugger/LuaPanda.lua \
  https://raw.githubusercontent.com/Tencent/LuaPanda/master/Debugger/LuaPanda.lua

步骤四：创建 VSCode 调试配置

在项目根目录创建 .vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lua",
            "request": "attach",
            "name": "LuaPanda Attach",
            "cwd": "${workspaceFolder}",
            "luaFileExtension": "",
            "connectionPort": 8818,
            "stopOnEntry": false,
            "useCHook": true,
            "autoPathMode": true
        }
    ]
}

步骤五：配置 OpenResty

在 nginx.conf 中添加 Lua 路径配置：

http {
    # LuaPanda 调试库路径 + luasocket 路径
    # 注意：~ 在 nginx 中不会展开，必须使用绝对路径
    lua_package_path "/Users/<用户名>/LuaProjects/debugger/?.lua;/Users/<用户名>/.luarocks/share/lua/5.1/?.lua;/Users/<用户名>/.luarocks/share/lua/5.1/?/init.lua;;";
    lua_package_cpath "/Users/<用户名>/.luarocks/lib/lua/5.1/?.so;/Users/<用户名>/.luarocks/lib/lua/5.1/socket/?.so;/Users/<用户名>/.luarocks/lib/lua/5.1/mime/?.so;;";

    server {
        listen 8088;

        location /test {
            content_by_lua_file lua/test.lua;
        }
    }
}

说明 ：将 <用户名> 替换为你的 macOS 用户名。路径解释：

• /Users/<用户名>/LuaProjects/debugger/?.lua - LuaPanda.lua 所在目录
• /Users/<用户名>/.luarocks/share/lua/5.1/?.lua - luasocket 的 Lua 文件
• /Users/<用户名>/.luarocks/lib/lua/5.1/?.so - luasocket 的动态库

步骤六：在 Lua 代码中启用调试

在需要调试的 Lua 文件开头添加：

require("LuaPanda").start("127.0.0.1", 8818)

完整示例 /Users/<用户名>/LuaProjects/debugger-test/lua/test.lua：

-- 引入 LuaPanda 调试器
require("LuaPanda").start("127.0.0.1", 8818)

-- 测试变量
local name = "OpenResty"
local version = 1.21
local items = {"apple", "banana", "orange"}

-- 测试函数
local function greet(who)
    local message = "Hello, " .. who .. "!"
    return message
end

-- 测试循环
local sum = 0
for i = 1, 10 do
    sum = sum + i
end

-- 调用函数
local result = greet(name)

-- 输出响应
ngx.say(result)
ngx.say("Sum: " .. sum)

步骤七：开始调试

1. 启动调试器 ：在 VSCode 中按 F5，选择 "LuaPanda Attach"，等待连接

2. 设置断点：在代码行号左侧点击设置断点

3. 启动 OpenResty ：

   # 进入你的 OpenResty 项目目录（包含 conf/、lua/、logs/ 的目录）
   cd /Users/<用户名>/LuaProjects/debugger-test
   openresty -p `pwd` -c conf/nginx.conf

   将路径替换为你实际的项目目录

4. 触发请求 ：

   curl http://localhost:8088/test

5. 断点命中：VSCode 会暂停在断点处，可查看变量、调用栈、单步执行

调试功能

命中断点后，可以：

• 查看变量：在左侧"变量"面板查看局部变量和全局变量
• 监视表达式：添加自定义表达式监视
• 调用堆栈：查看函数调用链
• 单步调试：F10 单步跳过，F11 单步进入
• 继续执行：F5 继续运行到下一个断点

常见问题

1. 报错 "please install luasocket!"

原因：luasocket 版本与 LuaJIT 不兼容。

解决：使用正确的命令安装：

luarocks --lua-dir=/usr/local/openresty/luajit --lua-version=5.1 install luasocket

2. 断点不命中

检查：

• VSCode 调试器是否已启动（状态栏显示"等待连接"）
• lua_package_path 和 lua_package_cpath 路径是否正确
• OpenResty 是否已重启

3. 警告 "writing a global Lua variable ('LuaPanda')"

这是 OpenResty 的全局变量写入警告，不影响调试功能，可忽略。

生产环境注意事项

• 调试代码会阻塞 worker 进程，仅在开发环境使用

• 上线前务必移除 require("LuaPanda").start(...) 代码

• 可通过环境变量控制是否启用调试：

  if os.getenv("DEBUG") then
      require("LuaPanda").start("127.0.0.1", 8818)
  end

总结

通过 VSCode + LuaPanda，我们可以在 OpenResty 项目中实现图形化断点调试，大大提升开发效率。关键点是确保 luasocket 使用 LuaJIT 编译，并正确配置 Lua 路径。

参考链接

• LuaPanda GitHub
• OpenResty 官方文档
• LuaSocket