必须先安装Lua解释器并配置PATH，再安装sumneko Lua和Lua Debug扩展；需在settings.json中正确设置lua.runtime.version和path；游戏脚本调试须用attach模式并确保游戏开启调试监听且脚本被真实加载。
安装Lua解释器和VSCode扩展
没有 lua 可执行文件，VSCode里所有“运行”“调试”都是空谈。先确认系统已装 Lua 5.1–5.4（推荐 5.4），Windows 用户别只下 luajit——它不兼容部分调试器协议。macOS/Linux 用 brew install lua 或源码编译；Windows 建议从 LuaForWindows 或 luadist 下带 lua.exe 的完整包，解压后把路径加进系统 PATH。
VSCode 扩展只装两个：
-
Lua（by sumneko，语言服务器，提供补全/跳转/诊断） -
Lua Debug（by actboy168，唯一支持断点/变量查看的调试器）
别装 EmmyLua——它调试能力弱、不维护，且与 sumneko 冲突。
配置 lua.runtime.version 和 lua.runtime.path
sumneko Lua 语言服务器默认按 Lua 5.1 行为解析语法，如果你用的是 table.unpack（5.2+）、goto（5.2+）或 utf8 模块（5.3+），不配版本会报一堆“undefined global”或“unexpected symbol”。
在 VSCode 设置（settings.json）里加：
"lua.runtime.version": "Lua 5.4", "lua.runtime.path": "/usr/local/bin/lua"
Windows 路径写成 "C:\Program Files\Lua\lua.exe"（注意双反斜杠）。lua.runtime.path 必须指向可执行文件，不是目录。设错会导致语言服务启动失败，状态栏显示 “Lua: Starting…” 卡死。
用 launch.json 启动游戏内脚本调试
游戏脚本调试 ≠ 直接运行 lua xxx.lua。多数游戏（如《星露谷物语》SMAPI、《泰拉瑞亚》tModLoader、自研引擎）要求脚本被宿主进程加载，调试器必须 attach 到该进程。
典型 .vscode/launch.json 配置（以 SMAPI 为例）：
{
"version": "0.2.0",
"configurations": [
{
"type": "lua",
"request": "attach",
"name": "Attach to SMAPI",
"port": 8080,
"host": "127.0.0.1"
}
]
}
关键点：
- 游戏侧必须启用调试支持：SMAPI 加
--debug启动，tModLoader 需打补丁或用tModLoader.Debug分支 - 端口必须一致，
port改了，游戏侧也得同步改 - 不要选
request: "launch"—— 它会起新lua进程，无法访问游戏内存和 API
常见错误现象：Debug adapter process has terminated unexpectedly，大概率是游戏没开调试监听，或防火墙拦了端口。
调试时看不到变量值或断点不命中
断点不生效，90% 是因为代码没被真实执行——比如函数定义了但没调用，或路径加载错了（require("mymod.main") 却把文件放在 mymod/init.lua）。
变量不可见的常见原因：
- 使用了
local变量且不在当前作用域（调试器只能看到栈帧里的 active 变量） - 游戏热重载机制绕过了调试器 hook（如 SMAPI 的
Reload Mod快捷键会跳过断点） - Lua 字节码被混淆或 strip 过（某些打包工具会删掉 debug info）
临时验证方式：在断点前加一句 print(debug.traceback())，看是否真走到这里。
如果变量名显示为 lua 解释器重试。
Lua 调试依赖宿主配合，不是装完插件就自动好用。最易忽略的是：游戏进程是否真的在监听调试端口，以及你的脚本是否被游戏实际加载并执行——这两步没确认，后面所有配置都白搭。
