必须先安装 Lua 可执行文件，再配置 sumneko.lua 扩展及 lua.runtime.path 和 lua.runtime.version，否则运行、调试、补全、跳转等功能均失效；需验证 lua -v 可输出版本，手动下载 lua-language-server 并重启服务器，且 require 标红须通过 .luarc.json 配置 runtime.path 显式声明模块路径。
必须先装 lua 可执行文件，再配 sumneko.lua 扩展和 lua.runtime.path，否则所有“运行”“调试”都是空谈。
确认系统已安装可用的 Lua 解释器
VSCode 本身不带 Lua 运行时，sumneko.lua 语言服务器需要调用本地 lua 或 luajit 来做类型推断、模块解析等。没这个二进制，补全、跳转、诊断都会出错或卡在 “Lua: Starting…”。
- Windows：别只下
luajit—— 它不兼容部分调试协议；推荐从 LuaForWindows 或 luadist 下完整包，解压后把含lua.exe的目录加进系统PATH - macOS/Linux：用
brew install lua@5.4 && brew link --force lua@5.4，或源码编译后确保which lua能输出路径 - 验证方式：终端执行
lua -v，必须返回类似Luajit 2.1.0-beta3或Lua 5.4.6；如果报 command not found，配置就还没生效
装对扩展并让语言服务器真正跑起来
sumneko.lua 是目前唯一能提供完整 LSP 支持（跳转、补全、诊断）的插件；它第一次启动会自动下载 lua-language-server，但这个过程常被网络卡住。
- 装完插件后，打开任意
.lua文件，状态栏右下角应显示Lua (running)；若一直卡在Downloading server，说明下载失败 - 手动补救：去 GitHub Releases 下最新
.zip，解压到%USERPROFILE%AppDataRoamingCodeUserglobalStoragesumneko.lua（Windows）或~/Library/Application Support/Code/User/globalStorage/sumneko.lua/（macOS） - 重启 VSCode，再按
Ctrl+Shift+P输入Restart Lua Server强制重载
必须配 lua.runtime.path 和 lua.runtime.version
这两个设置决定语言服务器“怎么理解你的代码”。设错会导致 table.unpack 标红、utf8.len 报 undefined、甚至整个项目无法加载。
-
lua.runtime.path必须指向可执行文件，不是目录。例如："C:\Program Files\Lua\lua.exe"（注意双反斜杠），或"/usr/local/bin/lua" -
lua.runtime.version要严格匹配你实际用的版本，如"Lua 5.4"、"LuaJIT 2.1"；写成"5.4"或"lua54"都不行 - 这两个字段要写进
settings.json（全局）或.luarc.json（项目级），后者优先级更高；改完必须重开文件或执行Restart Lua Server
为什么 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 库（比如
luv），也要手动加进runtime.path，node_modules不会自动扫描 - 嵌入式或游戏项目还要加
"diagnostics.globals"，比如["node", "tmr"]或["love", "cc"]，否则引擎 API 全标红
最易被忽略的是：所有配置改完后，不执行 Restart Lua Server 就等于没改。语言服务器不会热重载 .luarc.json 或 settings.json 里的路径和版本声明，必须手动触发——这是绝大多数“明明配了却没效果”的根本原因。
