必须安装sumneko.lua插件（作者sumneko，图标为蓝色“l”或蛇形图案）和actboy168.lua-debug插件，缺一则无语法提示、跳转、诊断或断点调试；需正确配置lua.runtime.path指向可执行文件，并在.luarc.json中设置runtime.path与runtime.version，修改后执行restart lua server。
sumneko.lua 插件必须装，否则所有语法提示、跳转、诊断都只是摆设；没它，VSCode 对 Lua 就是纯文本编辑器。
装对插件，别被名字骗了
VSCode 扩展市场搜 Lua，只认作者是 sumneko 的那个（图标是蓝色“L”或蛇形图案），别点 EmmyLua、Lua（by castorini）、Run on Save 这类老插件——它们连 require 路径解析都没有，table.unpack 报红、utf8.len 标黄，全是常态。
调试功能必须额外装 actboy168.lua-debug，sumneko.lua 本身不处理断点和变量查看。两个插件缺一不可，装完都要重启 VSCode。
常见错误现象：
• 状态栏右下角没出现 Lua (running)
• Ctrl+Click 变量跳不到定义
• require "xxx" 一直标红，但运行时其实能加载
lua.runtime.path 配错，语言服务器根本起不来
sumneko.lua 启动时要调用本地 Lua 解释器做 AST 分析，不是可有可无的配置项。它失败的最常见原因就是 lua.runtime.path 指向错误。
- 必须指向可执行文件，比如
/usr/local/bin/lua（macOS/Linux）或C:\Program Files\Lua\lua.exe（Windows，注意双反斜杠或正斜杠） - 不能指向目录，也不能写成
C:lua这种路径 - 终端里先跑
lua -v确认能输出版本，再配这个字段 - 如果系统 PATH 已包含
lua，VSCode 设置里仍建议显式指定，避免 fallback 到默认的 5.1 行为（导致goto、utf8全报错）
验证方式：打开任意 .lua 文件，看状态栏右下角是否显示 Lua (running) —— 没这个，后面所有功能都是空转。
.luarc.json 里不配 runtime.path，require 就永远标红
sumneko.lua 默认只扫描工作区根目录下的 ?.lua 和 ?/init.lua，完全不读取运行时的 package.path。你项目结构是 src/utils/string.lua，写 require "utils.string"，它就直接报 Module not found。
解决方法是在项目根目录建 .luarc.json，写入：
{"runtime.path": ["src/?.lua", "src/?/init.lua"]}
关键点：
- 路径是相对于工作区根目录的，不是相对于当前文件
- 多个路径用数组，顺序影响查找优先级
- 如果用了 Lua 5.4+，必须加
"runtime.version": "Lua 5.4"，否则table.pack、string.match新参数会误报 - 改完后要手动执行命令
Restart Lua Server（Ctrl+Shift+P输入即可），不重开文件也生效
调试必须分清 launch 和 attach，混用等于白配
launch.json 里 "request" 字段只有两个合法值："launch" 和 "attach"，选错就进不了断点。
-
"request": "launch"：适合独立运行的 Lua 程序（如love .、lua main.lua）。此时"program"填解释器路径（如"love"或"lua"），"args"填项目参数 -
"request": "attach"：用于游戏脚本、嵌入式 Lua（如 xLua、tModLoader、SMAPI）。游戏进程必须已开启调试监听（如加--debug参数），且"port"与游戏侧一致 - 常见错误：
"type": "lua"写成"luajit"或"lua-debug"；"request": "launch"却去连 SMAPI，结果断点全灰、变量为空
最容易被忽略的是：lua-debug 插件本身不启动任何服务，它只是个客户端。你得确保游戏或宿主环境真的加载了调试 stub（比如 debugger.lua），并且防火墙没拦端口。
