<p>VSCode 要真正支持手游 Lua 开发（如 xLua、ToLua、Cocos Creator），必须同时配置 sumneko.lua（提供 LSP 补全）和 lua-debug（实现断点调试），缺一不可；sumneko.lua 是唯一可靠插件，因其基于 LSP 支持 luadoc 解析与类型推导，而 lua-debug 是唯一能协同完成 attach 模式调试的后端，xLua 等需在 C# 层调用 StartDebugger 并严格匹配 launch.json 的 host/port。</p>
VSCode 要真正支持手游 Lua 开发（比如 xLua、ToLua、Cocos Creator 或自研引擎嵌入式 Lua），光装一个插件远远不够——必须同时配对 sumneko.lua（LSP 补全）和 lua-debug（断点调试），否则补全会漏引擎 API，调试根本起不来。
为什么 sumneko.lua 是唯一靠谱的补全插件
它基于 Language Server Protocol，能解析 luadoc 注释、推导表结构、识别跨文件引用。其他插件（如 EmmyLua、Lua Helper）在 xLua 场景下常把 C# 导出的类识别成 any，导致补全失效或跳转错乱。
- 安装后必须重启 VSCode，状态栏右下角出现
Lua (running)才算语言服务器启动成功 - 不要手动下载服务器二进制：首次打开
.lua文件时，插件会自动弹窗提示“Download”，点它就行（2026 年最新版已默认带 Lua 5.4 支持） - 若项目用 xLua，
.luarc.json中必须加"defines": ["XLUA"]，否则XLua.LuaEnv等类型不被识别
lua-debug 才是断点调试的唯一入口
VSCode 官方 Lua 插件本身不提供调试能力，lua-debug（actboy168 维护）才是实际执行断点、变量监视、调用栈展开的后端。它和 sumneko.lua 协同工作，不是可选组件。
- 必须单独安装扩展
lua-debug（不是sumneko.lua自带的） - 调试 xLua 项目时，
launch.json必须用"request": "attach"模式，并指定"host": "127.0.0.1"和"port": 8888（与 C# 层XLua.LuaEnv.StartDebugger("127.0.0.1:8888")严格一致） - 若调试 Cocos Creator 的 Lua，需确保构建时勾选“启用远程调试”，且防火墙放行对应端口（默认 7001）
补全不显示 xlua、tolua 或 cc？检查这三个地方
这是手游开发中最常卡住的点：补全有，但全是标准库，引擎 API 全标红或没提示。
-
.luarc.json中的"diagnostics.globals"只影响错误检查，**不影响补全**；补全依赖的是类型定义（.d.lua）或 LSP 的 define 注入 - 确认
settings.json里没有开启javascript.suggest.autoImports—— 它会劫持.触发的补全，让cc.后无法弹出cc.Node等类 - xLua 项目建议在根目录放一个
xlua.d.lua，内容至少包含declare module 'xlua' { export const LuaEnv: typeof XLua.LuaEnv }，否则xlua.补全为空
调试器连不上？先看 love 或 tolua 是否加载了 debug stub
手游 Lua 调试失败，90% 不是 VSCode 配置问题，而是目标进程没加载调试桩。xLua、tolua、Cocos 都需要显式初始化调试器。
- xLua：C# 层必须调用
env.StartDebugger()，且不能在OnDestroy后调；Unity Editor 下需额外勾选 “Development Build” - tolua：需在 Lua 启动脚本开头插入
require "debugger"（该文件由 tolua 工具生成，路径通常为Assets/Plugins/ToLua/Debugger/debugger.lua） - Cocos Creator：只支持 v3.x 的 Lua 项目，v2.x 已废弃调试协议；启动时命令行加
--remote-debug参数才生效
最易忽略的是：xLua 的 StartDebugger 默认绑定 0.0.0.0:8888，但 VSCode launch.json 若写成 "host": "localhost"，在某些 macOS 网络配置下会 DNS 解析失败——直接写 "host": "127.0.0.1" 更稳。
