vscode本身不运行lua，真正执行代码的是本地安装的lua或luajit可执行文件；若未配置path或解释器缺失，则f5、ctrl+alt+n等操作均无效，调试器也无法启动。
VSCode 本身不运行 Lua，它只负责编辑和调试；真正执行代码的是你本地装的 lua 或 luajit 可执行文件。没这个文件，点 F5、按 Ctrl+Alt+N、甚至装再多插件，都只是“假装在运行”。
为什么点 F5 没反应，或者报错 “command 'lua.runFile' not found”
这是最常踩的第一个坑：VSCode 插件（包括 sumneko.lua）默认不自带 Lua 解释器，也不自动调用系统 PATH 里的 lua —— 它只在需要做静态分析（比如跳转、补全）时才读取 lua.runtime.path，而运行/调试是另一套逻辑。
- 如果你装了
Code Runner插件，它会尝试调用终端命令lua ${file}，但前提是终端里输入lua -v能成功返回版本号 - 如果你用 sumneko + lua-debug 的调试模式，
request: "launch"会去跑program字段指定的脚本，但它不关心你有没有lua，只管把路径丢给调试器——而调试器底层仍需调用真实解释器 - Windows 用户尤其容易卡在这：下了 LuaForWindows 却没把
lua.exe所在目录加进系统 PATH；或只下了 LuaJIT，但某些调试协议（如 vscode-lua-debug）对 LuaJIT 支持不稳定
怎样让 Ctrl+Alt+N 真正跑起来（Code Runner 方案）
这个组合适合快速验证小脚本，不用配一堆 JSON 文件。但必须确保终端能认出 lua：
- 打开 VSCode 内置终端（
Ctrl+`），输入lua -v；如果报“不是内部或外部命令”，说明 PATH 没配好，先去系统环境变量里加上 Lua 安装目录（如C:\Program Files\Lua\5.4\） - 在 VSCode 设置中搜
code-runner.executorMap，找到lua对应项，确认它是"lua -e \"dofile('${file}')\""或更简单的"lua ${file}" - 别用中文路径存脚本——Code Runner 在 Windows 下遇到含中文的
${file}路径大概率崩溃，哪怕文件名是中文也不行 - 如果脚本依赖
package.path（比如 require "utils"），Code Runner 不加载你的配置，得手动改init.lua或在脚本开头加package.path = "./?.lua;" .. package.path
为什么断点设了却不生效（lua-debug 启动模式）
这通常不是插件问题，而是 launch.json 配错了关键字段，导致调试器根本没连上 Lua 进程：
-
"type": "lua"必须小写，写成"Type"或"LUa"都会静默失败 -
"request": "launch"表示 VSCode 自己拉起一个新 Lua 进程；如果你的脚本要访问游戏 API（如love.graphics）或嵌入式模块（如node.chipid），这种模式无效——你得用"request": "attach"并让宿主进程主动监听 -
"program": "${file}"是常见写法，但若脚本里有arg[0]相关逻辑，它传进去的是空字符串，不是文件路径；建议显式写成"program": "${workspaceFolder}/main.lua" - macOS/Linux 用户注意：
lua-debug的二进制适配器（lua-debug.so）必须和你系统 Lua 版本 ABI 兼容；用brew install lua@5.4装的，就别拿从源码编译的 5.1 版本适配器混用
中文变量名能用，但调试时看不到值
中文标识符语法上完全合法（Lua 5.3+ 原生支持 UTF-8），但调试器显示乱码或空白，本质是符号序列化环节丢掉了编码信息：
- VSCode 终端默认编码不是 UTF-8：Windows 用户需在终端右键 → 属性 → 将“当前代码页”改为 65001（UTF-8）；macOS/Linux 一般没问题，但检查
locale输出是否含UTF-8 -
lua-debug旧版（v1.52 之前）对 Unicode 变量名支持不完整，升级到最新 release（截至 2026 年 4 月是 v1.55+） - 不要在
.luarc.json里写"runtime.version": "Luau"来硬凑 Roblox 场景——Luau 是分支，和标准 Lua 调试协议不兼容，会导致变量面板直接失联 - 如果用了自定义调试桥接（如 ZeroBrane Studio），它的控制台可能仍走 ANSI 编码，中文输出正常，但 VSCode 变量面板里仍是
???，这是协议层限制，非配置可解
真正麻烦的从来不是“怎么配”，而是“配完发现某个环节悄悄绕过了你的配置”。比如 lua.runtime.path 设了，但 Code Runner 根本不读它；又比如 launch.json 写对了，但游戏没开 --debug，VSCode 就在那儿干等连接超时。这些隐性依赖，才是调试失败时最该先盯住的地方。
