Cocos / Unity / OpenResty

通用注意

• 使用 LuaDebug 前请禁用其它 Lua 调试扩展。
• 先启动编辑器调试，再启动游戏。
• 调试文件从扩展目录 luadebug 拷贝到工程可 require 的位置。
• LuaJIT 环境用 LuaDebugjit.lua；标准 Lua 用 LuaDebug.lua。

Cocos（Creator / cocos2d-x Lua · 2.x / 3.x）

准备工作

1. 拷贝 LuaDebug.lua 或 LuaDebugjit.lua 到脚本目录。
2. 在入口脚本（如 main.lua）尽早 require，并把回调挂到调度器：

local breakSocketHandle, debugXpCall = require("LuaDebugjit")("127.0.0.1", 7003)
cc.Director:getInstance():getScheduler():scheduleScriptFunc(breakSocketHandle, 0.3, false)

生成 / 添加调试配置

• 无 launch.json：创建并选择 LuaDebug。
• 已有：添加配置 → LuaDebug: Cocos2-launch 或 LuaDebug: Cocos remote。

本地 launch 示例

{
  "name": "Cocos2-launch",
  "type": "lua",
  "request": "launch",
  "runtimeType": "Cocos2",
  "localRoot": "${workspaceFolder}",
  "commandLine": "-workdir ${workspaceFolder}/../ -file src/main.lua",
  "port": 7003,
  "exePath": "",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "printType": 1
}

exePath 填模拟器 / player 绝对路径。Windows 填 .exe；macOS 填 .app/Contents/MacOS/可执行名。

localRoot 相当于工程 workdir，告诉调试器脚本根在哪。

远程 / 真机 attach 示例

{
  "name": "COCOS(remote debugging)",
  "type": "lua",
  "request": "attach",
  "runtimeType": "Cocos2",
  "localRoot": "${workspaceFolder}",
  "port": 7003,
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "printType": 1
}

游戏侧 StartDebug 的 IP：本机可用 127.0.0.1；真机填电脑局域网 IP。若报 module 'socket.core' not found，见 FAQ。

Cocos commandLine 常用参数

launch 的 commandLine 会传给模拟器，常见项：

Cocos 4.0 注意

Cocos 4.0 对命令行做了调整：-file 可能已无效。请按官方 4.x 启动方式配置，并保证入口脚本已接入调试代码。

建议：用编辑器只打开脚本目录（如 src），在该目录下维护 launch.json。

local breakSocketHandle, debugXpCall = require("LuaDebugjit")("127.0.0.1", 7003)
cc.Director:getInstance():getScheduler():scheduleScriptFunc(breakSocketHandle, 0.3, false)

Unity · xLua

注意 DoString / AddLoader

若用 luaEnv.DoString 加载脚本，第二个参数 chunkname 必须填真实文件路径/文件名。若 chunkname 带 .txt 导致对不上，可尝试去掉后缀再传入。自定义 AddLoader 时同样要保证 chunk 名称可映射到磁盘路径。

接入调试

1. 将调试文件放入 Lua 脚本目录。
2. 在 Lua 启动逻辑中 require 并 StartDebug。
3. launch 选择 LuaDebug: Unity-xlua，runtimeType 为 Unity。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Unity-xlua",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Unity",
      "localRoot": "${workspaceFolder}",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    }
  ]
}

顺序：编辑器 F5 → Unity 运行会执行到 StartDebug 的入口。API 提示可设 "luadebug.apiType": "xlua"（与能否断点无关）。

Unity · sLua

早期 sLua（如 1.5.1 之前）可能未自带 LuaSocket，需先集成 socket。

1. 拷贝调试文件并在 Lua 启动处 StartDebug。
2. launch 使用 LuaDebug: Unity-slua。
3. 确认运行时加载的脚本与编辑器源码一致（注意 AB 包）。

{
  "name": "Unity-slua",
  "type": "lua",
  "request": "attach",
  "runtimeType": "Unity",
  "localRoot": "${workspaceFolder}",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "port": 7003,
  "printType": 1
}

Unity · uLua / toLua

1. 拷贝匹配的调试文件到 Lua 目录。
2. 在启动 Lua 中 require + StartDebug。
3. launch 可选 Unity-ulua；toLua 同样 runtimeType: Unity，localRoot 指到实际脚本根。
4. 自定义 loader / DoFile 时 chunkname 必须可映射到真实路径。

{
  "name": "Unity-ulua",
  "type": "lua",
  "request": "attach",
  "runtimeType": "Unity",
  "localRoot": "${workspaceFolder}",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "port": 7003,
  "printType": 1
}

建议顺序：编辑器下断点并启动调试 → Unity 运行 → 确认断点命中。

OpenResty

1. 打开工程；脚本根目录示例为 src（名字任意）。
2. 将插件提供的 OpenResty / JIT 调试文件拷贝到脚本根，并在初始化阶段接入 StartDebug。
3. launch 添加 LuaDebug: OpenResty。
4. 注意 worker 进程模型：只在需要调试的进程启用，并放行端口。

{
  "name": "OpenResty",
  "type": "lua",
  "request": "attach",
  "runtimeType": "OpenResty",
  "localRoot": "${workspaceFolder}",
  "port": 7003,
  "fileExtNames": [".lua"],
  "printType": 1
}

非 Cocos / Unity 的独立程序

只要运行时能加载 Lua 并支持 LuaSocket，即可在入口调用 StartDebug。launch 使用 attach，localRoot 指到脚本根即可。

真机调试

1. 手机与电脑同一局域网。
2. StartDebug 的 host 填电脑局域网 IP（不要用 127.0.0.1）。
3. port 与 launch 一致；关闭会拦截该端口的防火墙。
4. 编辑器先 F5，再启动手机上的应用。

loxodon-framework-xlua 无法调试

部分框架对脚本加载封装较深，若断点无法绑定，请检查：

• DoString / loader 的 chunkname 是否为真实路径；
• 运行时读取的是否为打包后的字节码 / AB，与编辑器源码不同步；
• localRoot 是否指向框架实际存放 Lua 的目录。

在「真正执行 Lua 文本」的位置接入 StartDebug，并保证 chunkname 可映射。