必须同时安装 lua debug（actboy168）和 lua by sumneko（sumneko）插件，前者实现断点调试，后者提供语言服务；launch.json 中 type 必须为 "lua"，且需使用兼容的 lua 5.1–5.4/luajit 解释器。
装对插件：Lua Debug 和 Lua by sumneko 是关键
VSCode 本身不支持 Lua 调试，必须依赖外部调试器 + 插件配合。只装 Lua 语法高亮插件（比如 Lua by sumneko）是不够的，它只提供智能提示和代码检查；真正实现断点、单步、变量查看，得靠 Lua Debug 插件（作者是 actboy168），它封装了 lua-debug 这个底层调试适配器。
两个插件都要装，缺一不可：
-
Lua Debug：负责与 VSCode 的 Debug 协议通信，启动调试会话 -
Lua by sumneko：提供语言服务器（LSP），支撑跳转、补全、诊断（注意：它自带的“运行”按钮只是执行lua命令，不支持断点）
别装错名字——搜 “Lua Debug” 时认准作者 actboy168；搜 “Lua” 时认准作者 sumneko。其他同名插件（如旧版 luaide 或 vscode-lua）已弃用或不兼容现代调试协议。
配置 launch.json：选对 type 和 request
调试启动配置写在项目根目录的 .vscode/launch.json 里，核心是 type 必须设为 "lua"（不是 "node" 或 "pwa-node"），且 request 为 "launch" 或 "attach"。
本地直接运行脚本用 "launch"，常见配置项含义：
-
program：要调试的入口文件路径，建议用${workspaceFolder}/main.lua这类相对路径 -
cwd：工作目录，影响require查找路径和io.open的相对路径，默认${workspaceFolder}即可 -
args：命令行参数数组，例如["--verbose", "test"]，不是字符串 -
console：设为"integratedTerminal"才能在 VSCode 内看到print输出
示例最小可用配置：
{
"version": "0.2.0",
"configurations": [
{
"type": "lua",
"request": "launch",
"name": "Debug Lua Script",
"program": "${workspaceFolder}/main.lua",
"cwd": "${workspaceFolder}",
"console": "integratedTerminal"
}
]
}
确保系统有可用的 lua 解释器且版本兼容
Lua Debug 插件底层依赖 lua-debug 适配器，它对 Lua 版本有硬性要求：仅支持 Lua 5.1、5.2、5.3、5.4 和 LuaJIT 2.0+。如果你用的是 luau、moonscript 或某些嵌入式定制版（如 Roblox Studio 自带的 Lua），调试会直接失败，报错类似 "cannot load module 'debug'" 或 "no debug hook support"。
验证方式很简单，在终端运行：
lua -v
输出必须是类似 Luajit 2.1.0-beta3 或 Lua 5.4.6。如果显示 luau 或版本号带 roblox 字样，就得换解释器——下载标准 Lua 或 LuaJIT，并把它的 bin 目录加进系统 PATH，再重启 VSCode。
断点不生效？先关掉 require 缓存和热重载干扰
常见现象：打了断点，F5 启动后却不停，控制台飞快跑完，变量窗口空空如也。大概率是代码被缓存或绕过了调试注入。
- 检查是否用了
package.loaded["mymodule"] = nil+require强制重载——这会跳过调试器对模块的 hook 注入，断点失效 - 确认没在代码里调用
debug.sethook或debug.getinfo等底层调试函数，它们会与lua-debug冲突 - 如果用
loadfile/load动态加载字符串代码，这些代码默认不被调试器跟踪，断点无效 - Windows 下杀毒软件有时会拦截
lua-debug的 DLL 注入，临时禁用试试
最稳妥的调试起点：用一个纯 main.lua 文件，只含 print("start") 和几行简单逻辑，不 require 其他模块，确认基础断点能停住，再逐步加功能。
调试器实际是把 Lua 解释器包装了一层，所有路径、环境变量、C 模块加载都得和你配置的 lua 可执行文件一致——很多人卡在“能运行不能调试”，问题就出在 VSCode 用的 lua 和终端里敲的不是同一个。
