必须先确保Crystal编译器已正确安装并加入PATH，再配置Sublime Text构建系统：新建Crystal.sublime-build文件，设置shell_cmd、file_regex、selector等字段，并安装Crystal语法高亮插件，否则构建将失败。
Sublime Text 本身不支持 Crystal，必须手动配置构建系统，且 Crystal 编译器 crystal 必须已安装并能被系统识别（即终端中运行 crystal --version 有输出），否则所有构建都会失败。
确认 Crystal 已正确安装并可用
这是最关键的前置条件，90% 的“构建失败”都卡在这一步。
- 打开终端（Windows 用 CMD/PowerShell，macOS/Linux 用 Terminal），执行：
crystal --version - 若提示
'crystal' is not recognized或command not found，说明未安装或未加入PATH - Crystal 官方安装方式见 crystal-lang.org/install；Windows 用户推荐用
scoop install crystal或从 GitHub Releases 下载预编译二进制包，并把crystal.exe所在目录加进系统环境变量PATH - 验证成功后，再继续 Sublime 配置 —— 否则后续所有 JSON 配置都白搭
创建 Crystal.sublime-build 构建系统
Sublime 不自带 Crystal 支持，需新建一个 .sublime-build 文件来定义编译与运行逻辑。
- 在 Sublime 中，菜单栏点击 Tools → Build System → New Build System…
- 清空默认内容，粘贴以下 JSON（兼容 Windows/macOS/Linux）：
{
"shell_cmd": "crystal build \"$file\" -o \"$file_path/$file_base_name\" 2>&1",
"file_regex": "^([^:]+):([0-9]+):([0-9]+): (error|warning): (.*)$",
"working_dir": "$file_path",
"selector": "source.cr",
"variants": [
{
"name": "Run",
"shell_cmd": "crystal build \"$file\" -o \"$file_path/$file_base_name\" && \"$file_path/$file_base_name\" 2>&1"
}
]
}
-
"selector": "source.cr"表示该构建只对.cr文件生效（需确保文件后缀为.cr） -
2>&1把错误输出也捕获到 Sublime 控制台，方便定位语法/类型错误 - Windows 用户若想在独立 CMD 窗口运行（支持交互式输入），可将
Run变体的shell_cmd替换为：crystal build \"$file\" -o \"$file_path/$file_base_name\" && start cmd /c \"\"$file_path/$file_base_name\" & pause\"
设置文件语法高亮与自动关联
默认新建的 .cr 文件不会高亮 —— Sublime 不知道它是 Crystal 代码。
- 打开一个
.cr文件，在右下角状态栏点击当前语法名（如 “Plain Text”） - 选择 Open all with current extension as… → Crystal
- 若列表里没有 “Crystal”，需先安装插件：
Ctrl+Shift+P→ 输入Package Control: Install Package→ 搜索并安装Crystal（作者：mehcode） - 安装后重启 Sublime，
.cr文件会自动使用 Crystal 语法高亮，且触发source.crselector，使构建系统生效
常见报错与绕过坑点
即使配置完成，实际使用时仍容易因细节翻车。
-
Could not find file 'xxx.cr'：检查文件是否已保存（未保存的临时标签页无$file路径） -
undefined method 'xxx' for Nil类型错误不显示行号：上面 JSON 中的file_regex已适配 Crystal 0.40+ 默认错误格式；旧版 Crystal 需调整正则，例如去掉第三组([0-9]+) - 中文路径或文件名导致构建失败：Windows 下建议避免中文路径；macOS/Linux 一般无此问题
- 构建后无输出或闪退：确认
Run变体是否被选中（Ctrl+Shift+B→ 选Crystal: Run），且程序内有gets或puts等 I/O 操作
Crystal 的构建本质是调用本地 crystal 命令，Sublime 只做管道和界面包装。真正要调试的永远是命令行能否跑通 —— 先在终端里 crystal run hello.cr 成功了，再让 Sublime 调它，顺序不能反。
