应安装 sumneko.lua 插件，它提供语法检查、跳转、断点调试等完整LSP支持；需配合 actboy168.lua-debug 实现调试，并正确配置 .luarc.json 和 launch.json。
装哪个插件才能真有语法提示和调试
VSCode 自身不支持 Lua，必须靠插件补全能力。目前唯一能同时提供可靠语法检查、跳转、断点调试的插件是 sumneko.lua（官方推荐，LSP 实现）。别装 lua 或 emeraldwalk.runonsave 这类老插件——它们只做基础高亮，没有语义分析，require 找不到模块、变量未定义也完全不报。
安装步骤很简单：
1. 在扩展市场搜 sumneko.lua，认准作者是 sumneko
2. 安装后重启 VSCode
3. 第一次打开 .lua 文件会提示下载服务器，点「Download」（自动选最新 Release）
4. 下载完自动启动，状态栏右下角出现 Lua (running) 才算就位
注意：Windows 用户如果卡在「Downloading server」，大概率是网络问题。可以手动下载压缩包，解压到 %USERPROFILE%\AppData\Roaming\Code\User\globalStorage\sumneko.lua，再重启。
为什么写了 require 还标红？路径和 package.path 没对上
Sumneko 默认只认当前工作区根目录下的 ?.lua 和 ?/init.lua，不读取运行时的 package.path。你项目里用 require "utils.string"，但文件实际在 src/utils/string.lua，它就直接报 Module not found。
解决方法只有改配置：
• 在工作区根目录建 .luarc.json
• 写入 "runtime.path"： 字段，比如：
{"runtime.path": ["src/?.lua", "src/?/init.lua"]}• 如果用 Lua 5.4+，还要加
"runtime.version": "LuaJIT 2.1" 或 "5.4"，否则 table.pack 等新 API 不识别• 修改后必须重开文件或执行命令
Restart Lua Server（Ctrl+Shift+P 输入即可）
常见坑：package.cpath 对应的 C 模块路径不用配——Sumneko 不处理二进制模块，标红也别管；另外 node_modules 里的 Lua 库（比如 luv）默认不扫描，得手动加进 path。
调试时断点不生效，其实是没配 launch.json 启动器
Sumneko 本身只做语言服务，调试靠另一个插件 actboy168.lua-debug（必须装，且和 sumneko.lua 兼容）。装完后，按 Ctrl+Shift+D → 点「create a launch.json file」→ 选 lua → 自动生成模板。
关键字段要手动调：
• "type": "lua"（不能写成 luajit 或 debug）
• "request": "launch"（不是 attach，除非你连外部进程）
• "program": "${file}"（当前文件）或写死路径如 "./main.lua"
• 如果脚本依赖环境变量或工作目录，加 "cwd": "${workspaceFolder}/bin"
断点不命中最常见两个原因：一是没点绿色 ▶️ 而是直接 F5（F5 默认运行的是终端命令，不是调试器）；二是 Lua 文件用了 os.exit() 或 error() 提前退出，调试器来不及响应。
Mac / Linux 上调试失败，十有八九是 lua 命令找不到或版本错
lua-debug 插件底层调用系统 lua 可执行文件。如果你用 brew install lua 装的是 5.4，但项目必须跑在 5.3 上，或者你用 luarocks 装的 Lua 在 /opt/homebrew/bin/lua，而 VSCode 终端 PATH 没加载它，就会报 Cannot find Lua interpreter 或直接闪退。
查清路径最稳的办法：
• 终端里运行 which lua 和 lua -v
• 把输出路径粘进 launch.json 的 "runtimeExecutable" 字段，例如：
"runtimeExecutable": "/opt/homebrew/bin/lua"
• 如果用 Luajit，路径通常是
/usr/local/bin/luajit 或 /opt/homebrew/bin/luajit，别写成 luajit-2.1
别信「全局 PATH 已设好」——VSCode 桌面版常读不到 shell 的 PATH，尤其 zsh 配了 ~/.zprofile 却没加载的情况。硬编码路径是最省心的解法。
复杂点在于：同一个项目可能在 Windows CI、Mac 本地、Linux 服务器上跑不同 Lua 版本。这时候 .luarc.json 的 runtime.version 和 launch.json 的 runtimeExecutable 得分开维护，漏一个就废一半功能。
