必须先安装Lua解释器并配置PATH，再安装sumneko Lua和Lua Debug扩展；需在settings.json中正确设置lua.runtime.version和path；游戏脚本调试须用attach模式并确保游戏开启调试监听且脚本被真实加载。
VSCode 本身不运行 Lua，它只是编辑器；真正执行代码的是你本地装的 lua 或 luajit 可执行文件。没这个文件，点 F5、按 Ctrl+Alt+N、甚至装了 Code Runner，全都会报错或静默失败。
确认系统已安装可用的 Lua 解释器
这是所有后续操作的前提，跳过这步，后面全是白忙活。
- 打开终端（macOS/Linux）或命令提示符（Windows），输入
lua -v—— 如果返回类似Lua 5.4.6就说明已装且在PATH中；如果提示“命令未找到”，就得先装 - Windows 用户慎选 LuaJIT：它不兼容
lua-debug调试协议，调试时大概率卡在 “Debug adapter process has terminated unexpectedly” - 推荐安装方式：
- macOS：用
brew install lua@5.4 && brew link --force lua@5.4 - Windows：从
luadist下带完整lua.exe的包，解压后把路径（如C:\luadist\bin）加进系统环境变量PATH
- macOS：用
用 Code Runner 快速运行单个 .lua 文件
适合写小工具、验证语法、跑测试脚本——不用配 launch.json，但也不支持断点、变量监视等调试功能。
- 安装扩展：
Code Runner（作者：Jun Han），不是Lua插件本身 - 确保
lua命令能全局调用，否则右键“Run Code”会失败，错误信息通常是command 'lua' not found - 运行方式：
- 快捷键：
Ctrl+Alt+N（Windows/Linux）或Cmd+Option+N（macOS） - 右键菜单 → “Run Code”
- 点击编辑器右上角 ▶️ 按钮
- 快捷键：
- 如果脚本秒退看不到输出，在末尾加一行
io.read()暂停终端
配置 launch.json 启动调试会话（支持断点/变量/调用栈）
这才是真正开发游戏脚本或复杂逻辑时该用的方式。注意：sumneko.lua 插件只负责语法提示，调试必须靠 lua-debug 扩展 + 正确的 launch.json 配置。
- 先装扩展：
Lua Debug（作者：actboy168），别装 EmmyLua 或老版 lua-debug.so 手动放的方案 - 按
Ctrl+Shift+D→ 点左上角齿轮图标 → 选lua→ 自动生成.vscode/launch.json - 关键字段必须改对：
-
"type": "lua"（不能是luajit或空） -
"request": "launch"（不是attach，除非你连外部游戏进程） -
"program": "${file}"表示运行当前打开的文件；也可以写死为"./main.lua" - 如果脚本依赖工作目录下的资源（如图片、配置），加上
"cwd": "${workspaceFolder}"
-
- 常见失败现象：“Breakpoint ignored because generated code not found”——大概率是
lua.runtime.path指向了目录而非可执行文件，或者lua.runtime.version没设对导致语言服务器解析失败
中文变量名和字符串能跑，但不一定能调
标准 Lua 5.3+ 允许 UTF-8 标识符（比如 姓名 = "张三"），VSCode 编辑器也能正常高亮，但调试器不一定能读取这些变量名的值。
- 终端乱码（显示 或方块）：不是 Lua 问题，是 VSCode 终端编码设置不对。Windows 用户需在终端右键 → “Configure Terminal Settings” → 把
terminal.integrated.defaultProfile.windows设为PowerShell，并确保 PowerShell 启动时执行[Console]::OutputEncoding = [System.Text.Encoding]::UTF8 - 调试时变量面板为空或乱码：目前
lua-debug对中文变量名的支持不稳定，尤其在嵌套表结构里。临时方案是调试阶段改用英文变量名，发布前再替换回来 - 真正稳定的中文支持需要整条链路适配：编辑器语法定义、终端渲染、调试协议序列化、宿主进程字符集——这不是改一个配置就能解决的事
