crystal在vscode跑不起来主因是crystal cli未进path或版本＜1.12.0；需验证which crystal、crystal --version，配置.crystalconfig启用lsp，tasks.json区分build/run，launch.json中program设为"${file}"并装lldb。
Crystal 在 VSCode 里跑不起来，大概率不是插件装错了，而是 crystal 命令本身没进 PATH 或版本太旧——所有高亮、跳转、补全、调试都依赖它。
确认 crystal CLI 是否可用且版本 ≥ 1.12.0
VSCode 的 Crystal 扩展（比如 Crystal Language Support）只是个“壳”，真正干活的是你本地的 crystal 可执行文件。它得能响应 crystal tool format、crystal tool lsp 这类子命令，否则 LSP 直接瘫痪。
- 在 VSCode 集成终端里运行
which crystal，输出必须是有效路径（如/opt/homebrew/bin/crystal），不能是空或command not found - 运行
crystal --version，确认输出 ≥1.12.0；低于此版本会缺失crystal tool lsp，导致补全失效 - 如果用
brew install crystal安装但which crystal找不到，检查是否漏了brew shellenv或 zsh 配置未重载（source ~/.zshrc） - Mac M 系列用户常见坑：Homebrew 默认装到
/opt/homebrew，但 VSCode 启动时可能没加载该路径，需在settings.json显式设"crystal.executablePath": "/opt/homebrew/bin/crystal"
启用 LSP 补全必须配 .crystalconfig，不是靠扩展开关
很多用户装完扩展就以为“自动有 Ruby 风格提示”，结果输 String. 没反应——因为默认关闭语义分析。Crystal 扩展不会自动开 LSP，必须项目级声明。
- 在项目根目录新建文件
.crystalconfig（注意开头是点，无后缀） - 内容只能是合法 JSON：
{"lsp": true, "auto-reload": true}，多一个逗号或引号都会让 LSP 启动失败 - 保存后，打开任意
.cr文件，状态栏右下角应显示Crystal (via LSP)，不是Crystal - 若仍无补全，用
crystal tool lsp --help测试命令是否可执行；不可执行说明编译器安装损坏或权限不对
tasks.json 要区分 build 和 run，别混用 crystal build 和 crystal run
crystal build 输出原生二进制，适合最终交付；crystal run 是解释+编译+执行三合一，开发期更顺手。两者参数、错误提示、problemMatcher 都不同，混用会导致“报错不跳转”或“生成文件却没运行”。
- 要一键运行当前脚本：用
crystal run ${file}，搭配"problemMatcher": ["$crystal"]，错误行可直接点击跳转 - 要生成可执行文件：用
crystal build ${file} -o ${fileBasenameNoExtension}，注意-o参数必须指定输出名，否则默认输出为./crystal（覆盖风险） - 别在
args里写["run", "${file}", "--error-trace"]——--error-trace是crystal全局 flag，得放在command后、args前，否则被当作文本参数忽略 - Windows 用户注意：
${fileBasenameNoExtension}在 PowerShell 下可能出错，建议改用${fileBasename}并手动删后缀，或切到 Git Bash 终端
调试前必须装 lldb，且 launch.json 中 program 字段不能带 crystal run
Crystal 0.40.0+ 内置 crystal debug 协议，但 VSCode 的 Crystal Debugger 扩展只负责转发，后端得靠 lldb（macOS）或 gdb（Linux）。断点灰掉、启动即退出，八成是后端没装或路径不对。
- macOS：运行
brew install lldb，验证lldb --version有输出；别用 Xcode 自带的 lldb，它常缺 Python 支持 - launch.json 的
program字段必须是"${file}"（源文件路径），不是"crystal run ${file}"—— 调试器只接受 Crystal 源码，由它自己调用crystal debug编译并注入 - 如果项目含
shard.yml，确保已运行shards install，否则调试时require失败，报cannot load such file - 断点只在
main函数及之后生效；lib/下的代码需在require后才能命中，别在shard.yml解析阶段打点
Crystal 的“Ruby 感”来自语法，但它的“C 级性能”和“调试能力”全系于 CLI 工具链是否干净——.crystalconfig 一行配置、tasks.json 里一个 -o 参数、launch.json 中少写一个 crystal run，都足以让整个体验从流畅变成卡死。别信“装完就跑”，每个环节都得亲手敲命令验证。
