必须同时安装sumneko.lua（作者sumneko）和lua debug（作者actboy168），前者提供语法补全、跳转与诊断，后者驱动断点调试；仅装其一无法实现完整调试功能。
VSCode必须装对两个插件才能断点
只装 sumneko.lua 或只装 Lua Debug 都不行——前者只提供语法补全和跳转，后者才是真断点的驱动器。必须同时安装：
-
sumneko.lua（作者 sumneko）：语言服务器，支撑require跳转、类型提示、错误诊断 -
Lua Debug（作者 actboy168）：调试协议桥接器，依赖底层lua-debug适配器
别搜“Lua IDE”或“EmmyLua”——它们已停止维护，且与 sumneko 冲突，会导致 launch.json 识别失败或断点标灰。
launch.json 必须用 attach 模式连接游戏进程
游戏脚本不是独立运行的 Lua 文件，不能用 "request": "launch" 直接执行。必须让 VSCode 主动连接正在运行的游戏宿主进程：
-
"type": "lua"—— 不是"emmylua_new"或"luapanda" -
"request": "attach"—— 表示 VSCode 是客户端，去连游戏端开启的调试服务 -
"port": 8888—— 默认端口，若被占需同步改游戏端启动参数（如lldebugger.start({ port = 9999 })） -
"pathMappings"必须显式配置：游戏里看到的路径（如/scripts/main.lua）→ 你本地 VSCode 工作区路径（如${workspaceFolder}/Assets/Scripts/main.lua）
漏掉 pathMappings 是断点标灰最常见原因，VSCode 根本找不到源码对应关系。
游戏端必须注入调试器并真实加载 Lua 脚本
VSCode 连上了不代表能断点——游戏侧没启调试、没加载目标文件，断点永远不触发：
- 确认调试器已注入：Windows 下把
lldebugger.dll放进游戏可执行文件同目录；LuaJIT 2.1+ 推荐用lldebugger，纯 Lua 5.3 可选mobdebug - 确认脚本被真实加载：在 C# 中调用
DoString或DoFile时，必须传入 chunkName，例如：luaEnv.DoString(textAsset.text, "Main.lua.txt")；否则 EmmyCore / lldebugger 无法将执行上下文映射到源文件 - 确认 Lua socket 已启用：xLua/ToLua 需手动调用
OpenLibs(LuaDLL.luaopen_socket_core)，否则require("socket.core")失败，调试器无法建连
chunkName 缺失是 Unity + XLua 项目断点失效的终极元凶，90% 的“连上了但断不了”都卡在这里。
调试器版本与 Lua 运行时必须严格匹配
lua-debug 仅支持 Lua 5.1–5.4 和 LuaJIT 2.0+，不兼容 Luau、MoonScript 或定制裁剪版：
- 在终端执行
lua -v确认版本；Unity + xLua 默认用 LuaJIT，别误装标准 Lua - VSCode 设置中必须指定
"lua.runtime.version"（如"Lua 5.1"），否则 sumneko 语言服务会按错误语法解析goto或utf8模块，报一堆 undefined global -
"lua.runtime.path"必须指向可执行文件（如C:\lua\lua.exe），不是目录；设错会导致状态栏卡在 “Lua: Starting…”
路径映射、chunkName、运行时版本——这三处只要有一处不严丝合缝，断点就只是个灰色装饰品。
