必须同时安装sumneko.lua和Lua Debug插件，缺一则断点标灰：前者提供语法补全、跳转与诊断等LSP功能，后者作为调试协议桥接器驱动断点；仅装其一无法实现完整调试。
必须同时装 sumneko.lua 和 Lua Debug，缺一不可——前者管语法、跳转、诊断，后者才是真断点的驱动器。
为什么只装一个插件断点标灰？
VSCode 本身不理解 Lua，所有智能功能都靠插件补全。sumneko.lua 是语言服务器（LSP），它能解析 require 路径、提示变量类型、标出未定义错误；但它不处理调试协议。Lua Debug（作者 actboy168）才是真正把 VSCode 和游戏进程连起来的桥接器，它依赖底层 lua-debug 适配器通信。两者分工明确：一个“看代码”，一个“控执行”。
常见错误现象：
- 装了
sumneko.lua却下不了断点 → 缺Lua Debug - 装了
Lua Debug但跳转失效、require报红 → 缺sumneko.lua - 搜“EmmyLua”或“LuaPanda”并安装 → 它们与
sumneko.lua冲突，会导致launch.json识别失败或断点永久标灰
launch.json 必须用 attach 模式，不能用 launch
Unity/Cocos/xLua 等环境里，Lua 脚本不是独立运行的可执行文件，而是被宿主进程（如 Unity.exe）加载执行的。所以 VSCode 必须作为客户端去连接已启动的游戏进程，而不是自己拉起一个 lua main.lua 进程。
关键配置项：
-
"type": "lua"—— 不是"emmylua_new"或"luapanda"，必须匹配已安装的Lua Debug插件 -
"request": "attach"—— 表示“附加到正在运行的进程”，这是热更新调试唯一可行模式 -
"port": 8888—— 默认端口，若被占用，需同步改游戏侧启动参数，例如lldebugger.start({ port = 9999 }) -
"pathMappings"必须显式写死：游戏里看到的路径（如/scripts/main.lua）→ 你本地文件路径（如${workspaceFolder}/Assets/Scripts/main.lua）。漏掉这条，VSCode 根本无法把断点位置映射到真实源码，断点必然标灰
游戏端没注入调试器 or chunkName 缺失 = 白连
VSCode 显示“已连接”不代表能断点。两个硬性前提必须同时满足：
- 调试器已注入：Windows 下把
lldebugger.dll放进游戏可执行文件同目录；LuaJIT 2.1+ 推荐用lldebugger，纯 Lua 5.3 可选mobdebug - 脚本被真实加载且带
chunkName：在 C# 中调用DoString或DoFile时，第二个参数必须传入可识别的文件名，例如luaEnv.DoString(textAsset.text, "Main.lua.txt")。xLua 项目中 90% 的“连上了但断不了”，根源都在这里——没有chunkName，调试器就无法把执行上下文绑定到源文件 - Socket 库必须启用：xLua/ToLua 需手动调用
OpenLibs(LuaDLL.luaopen_socket_core)，否则require("socket.core")失败，调试器建连直接中断
lua.runtime.version 必须和实际运行时严格一致
sumneko.lua 会根据这个配置决定语法解析规则。Unity + xLua 默认用 LuaJIT，不是标准 Lua；如果 VSCode 设置里写成 "lua.runtime.version": "Lua 5.3"，而实际跑的是 LuaJIT 2.1，就会出现函数签名错判、goto 语法报错等奇怪问题。
操作步骤：
- 先在终端执行
lua -v或查引擎文档确认真实运行时版本 - 在 VSCode 设置中显式指定：
"lua.runtime.version": "LuaJIT 2.1"或"Lua 5.1"等 - 别依赖自动检测——它经常猜错，尤其在混合环境（如 Cocos + 自定义 Lua 构建）下
最易被忽略的点：路径映射（pathMappings）和 chunkName 是两个独立又必须共存的环节。一个写错，断点就失效；两个都对，才真正打通从 VSCode 到游戏内存的完整链路。
