调试 · LuaDebug

调试文件从哪里来

插件安装目录下的 luadebug 文件夹内含运行时文件。更新扩展后请重新拷贝，并确认运行时实际加载的就是这份文件（Unity 尤其要避免仍在跑旧 AssetBundle）。

LuaDebug.lua — 标准 Lua
LuaDebugjit.lua — LuaJIT
OpenResty 版本 — 见框架对接 · OpenResty

设置项 luadebug.automaticDownloadingDebugFile 已废弃：插件不再自动弹窗下载调试文件。

连接顺序

编辑器启动调试会话（监听 launch 里的 port）。
游戏 / 客户端启动并执行 StartDebug(host, port)。
端口一致；真机时 host 为电脑局域网 IP。

如何添加 launch 配置

打开「运行和调试」面板。
没有 launch.json：点「创建 launch.json」→ 选 LuaDebug。
已有 launch.json：点「添加配置…」→ 选 LuaDebug: … 片段。
按引擎改字段；端口必须与 StartDebug 一致。

同时装多个 Lua 调试插件时，务必只保留 LuaDebug，否则 type=lua 会被其它扩展抢走。

{
  "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
    }
  ]
}

launch 里常改的字段

字段	说明
`name`	调试下拉框显示的名字
`type`	固定 `lua`（界面显示为 LuaDebug）
`request`	`launch` 由编辑器拉起程序；`attach` 等待进程连上
`runtimeType`	Cocos2 / Cocos3 / Unity / OpenResty / LuaTest 等
`localRoot`	本地脚本根，用于堆栈路径映射；填错会导致断点错文件 / 乱跳
`port`	调试端口，默认 7003，须与 StartDebug 一致
`exePath`	launch 模式下可执行文件路径（模拟器 / player）
`commandLine`	传给模拟器的参数（Cocos 常用）
`mainFile`	部分配置下的启动脚本名
`fileExtNames`	引擎里 Lua 可能用的后缀
`printType`	1 控制台+系统；2 仅控制台；3 仅系统

各引擎完整示例见框架对接。

LuaTest：直接调试某个 Lua 文件

launch 中选择 LuaTest 可在不启动完整游戏的情况下调试当前 / 指定 Lua 文件。

{
  "name": "LuaTest",
  "type": "lua",
  "request": "launch",
  "runtimeType": "LuaTest",
  "mainFile": "${fileBasenameNoExtension}",
  "localRoot": "${fileDirname}",
  "curFileExtname": "${fileExtname}",
  "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
  "port": 7003,
  "printType": 1
}

macOS 若出现 Permission denied，检查扩展目录与临时脚本执行权限，或在「隐私与安全性」中允许相关程序。

一个工作区多个游戏目录（乱跳文件）

多个相似目录时，调试器可能按 package.path / chunkname 猜错文件。为每个游戏写独立配置，并精确设置 localRoot：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "调试 src1",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Cocos2",
      "localRoot": "${workspaceFolder}/src1",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    },
    {
      "name": "调试 src2",
      "type": "lua",
      "request": "attach",
      "runtimeType": "Cocos2",
      "localRoot": "${workspaceFolder}/src2",
      "port": 7003,
      "fileExtNames": [".lua", ".txt", ".lua.txt", ".bytes"],
      "printType": 1
    }
  ]
}

调试面板里选择对应配置再 F5。非 Cocos 项目同样只需关注 localRoot。