Sublime Text 配置 Lua 开发环境：从零到可运行的核心指南
首先得明确一个核心前提：Sublime Text 本身并不内置 Lua 解释器，它也无法直接运行 Lua 脚本。它的角色更像一个高效的调度员，负责调用你系统里已经安装好的 lua 或 luajit 命令。所以，一切配置的起点，必须是确保在终端里敲下 lua -v 能正常响应。如果这一步没通过，后面所有的构建配置都将是空中楼阁。
第一步：确认终端里的 lua 命令确实可用
这往往是新手最容易跳过、却导致90%失败率的环节。别急着在 Sublime 里写配置，先打开你的终端验证一下。
- Windows 用户：打开 CMD 或 PowerShell，执行
where lua。如果没有任何输出，那只有两种可能：要么 Lua 根本没安装，要么安装路径没有添加到系统的 PATH 环境变量里。这时，你需要去 luabinaries 官网下载对应版本的lua-5.4.x_Win64_bin.zip，解压后，将包含lua.exe的目录（例如C:\lua\）手动添加到系统环境变量 PATH 中。 - macOS 用户：在终端执行
which lua。如果返回为空，通常可以通过 Homebrew 安装：brew install lua（对于 Apple Silicon 芯片的 Mac，更推荐安装特定版本：brew install lua@5.4）。这里有个隐藏陷阱：通过图形界面启动的 Sublime Text，可能读取不到你在 Shell 配置文件里设置的 PATH。稳妥起见，最好记下 Lua 解释器的实际安装路径（比如/opt/homebrew/bin/lua），在后续配置中直接使用绝对路径。 - Linux 用户：运行
which lua5.4或ls /usr/bin/lua*查看。很多 Linux 发行版默认的命令名是lua5.4而非简单的lua，这一点必须与你后续在 Sublime 构建系统里写的"cmd"字段保持完全一致。 - 验证成功后，务必重启一次 Sublime Text。因为 Sublime 只在启动时读取一次环境变量，修改 PATH 后不重启，它依然“看不见”新路径。
第二步：新建构建文件，关键字段一个都不能错
Sublime 的构建系统基于 JSON 格式，语法极其严格。多一个逗号、误用了中文引号、或者缩进混乱，都可能导致配置静默失效——按下 Ctrl+B 毫无反应，也不会有任何错误提示。
"cmd"字段是灵魂，必须与你系统里真实可用的命令匹配。如果which lua没结果但which luajit有，这里就应该写成["luajit", "$file"]。对于 Windows 用户，建议明确写上["lua.exe", "$file"]，可以避免一些扩展名解析的潜在问题。"selector": "source.lua"这一行是硬性要求。没有它，Sublime 根本不会对.lua文件启用这个构建系统。如果你安装了lua-enhanced这类语法增强插件，它注册的语法范围可能是source.lua.enhanced，那么这里的selector值也需要同步更改。"file_regex"决定了错误信息能否被正确解析并支持点击跳转。Lua 标准的错误格式类似test.lua:5: attempt to call a nil value，推荐使用"^(*?):([0-9]+):?([0-9]*):? (.*)$"来匹配。如果使用luajit，其错误信息末尾可能包含列号（如:5:12），那么正则就需要调整为"^(.*?):([0-9]+):([0-9]+):"。- 特别注意，不要尝试在
cmd中使用 Shell 语法。像"shell_cmd": "cd $file_path && lua $file_name"这样的写法是行不通的，&&符号会导致构建直接失败。
第三步：破解中文路径、闪退、无输出等典型难题
这些问题表面上看像是 Sublime Text 的 Bug，但根源大多在于文件路径编码、进程控制或输入输出限制。
- 报错 “cannot open xxx: No such file or directory” （尤其在 Windows 上）：这通常不是文件真的不存在，而是路径编码问题。Sublime Text 可能以 ANSI（如 GBK）编码传递包含中文的路径，而旧版本的
lua.exe（5.4 之前）只认 UTF-8 编码的路径。最彻底的解决方案是：将你的.lua脚本移动到纯英文的目录路径下（例如D:/code/test.lua）。 - Windows 下按下 Ctrl+B 后，控制台窗口一闪而过，看不到
print()的输出：这不是 Sublime 的问题，而是因为 Lua 进程执行完毕后立即退出了。有两个解决办法：一是在你的 Lua 脚本末尾加上io.read()来等待一个输入；二是修改构建系统，使用"cmd": ["cmd", "/c", "lua", "$file", "&&", "pause"]来让窗口暂停。 - 输出面板一片空白，没有任何内容：检查你的脚本中是否误用了
io.read()或os.execute("pause")这类需要等待标准输入（stdin）的命令。Sublime Text 的输出面板并不支持交互式输入，这些语句会导致构建进程卡住或静默退出。 - 编辑器右下角状态栏显示 “Plain Text” 而不是 “Lua”：这说明语法高亮没有生效。可以先按
Ctrl+Shift+P，输入Set Syntax: Lua手动切换。如果下拉列表中没有 Lua 选项，你需要先通过 Package Control 安装LuaEnhanced这类语法插件。
长期维护与调试的隐藏要点
真正的挑战往往不在于“如何配置成功”，而在于“如何让配置稳定、持久地工作”。
- 构建文件的存放位置至关重要。通过
Preferences → Browse Packages…打开的Packages/User/目录是唯一推荐且安全的保存位置。请确保你的Lua.sublime-build文件放在这里，而不是桌面或下载文件夹。 - macOS 上的 PATH 继承问题：如果从 Finder（访达）启动 Sublime，它很可能丢失你在 Shell 中配置的 PATH。一劳永逸的解决方法是始终从终端启动 Sublime：在终端输入
subl命令（前提是已配置好命令行工具），这样 Sublime 就能继承完整的终端环境变量。 - 谨慎使用路径变量：在构建系统中，
$file代表文件完整路径，$file_path代表文件所在目录。尽量不要依赖$file_name或$file_base_name进行复杂的路径拼接，它们在特定场景下可能为空或产生意外结果。 - 明确工作目录：如果你的脚本需要读取同目录下的其他文件（比如
assets/config.json），务必在构建系统中显式设置"working_dir": "$file_path"。否则，io.open("config.json")默认会在 Sublime Text 的安装目录下寻找文件，导致“文件不存在”的错误。
