必须先确保系统及VSCode终端中crystal CLI可用且版本≥1.12.0，再启用官方Crystal插件、配置.crystalconfig启用LSP，方可实现补全、跳转、格式化等完整功能。
Crystal 在 VSCode 里没补全、不跳转、格式化报错、甚至 crystal run 都提示 command not found —— 这不是插件装得不对，而是本地 crystal CLI 根本没跑通。必须先让终端和 VSCode 内置终端都能一致地执行 crystal --version 和 crystal tool lsp，否则所有功能都是空谈。
确认 crystal CLI 可用且版本 ≥ 1.12.0
VSCode 的 Crystal 插件不带编译器，它只调用你系统里的 crystal 命令。低于 1.12.0 就没有 crystal tool lsp，LSP 功能直接失效。
- 在系统终端（不是 VSCode 里）运行
which crystal和crystal --version，确认输出路径有效、版本 ≥ 1.12.0 - 在 VSCode 内置终端（
Ctrl + `）中重复执行这两条命令，结果必须和系统终端完全一致；若显示/usr/bin/crystal或command not found，说明 VSCode 启动时没加载你的 shell 配置（如~/.zshrc） - Mac M 系列用户：Homebrew 默认装到
/opt/homebrew/bin/crystal，但 VSCode 常常找不到它，需在settings.json中显式指定："crystal.executablePath": "/opt/homebrew/bin/crystal" - Linux 手动编译安装用户：确保
crystal/bin已加入$PATH，且能正常运行crystal env输出 SDK 路径 - Windows 用户：官方无稳定二进制，唯一可行路径是 WSL2 + Ubuntu，别试 CMD/PowerShell 原生环境
只启用官方 Crystal Language Support 插件
社区存在多个 Crystal 扩展，但只有作者为 crystal-lang 的那个是官方维护、内建 LSP、无需额外配 scry 的方案。其他扩展要么停更，要么协议过时，会干扰语言识别。
- 卸载所有 Ruby 相关插件：尤其是
Solargraph、ruby-solargraph、rebornix.ruby，它们会劫持text/ruby模式，导致.cr文件被识别成 Ruby - 安装后重启 VSCode，打开任意
.cr文件，右下角状态栏应显示Crystal (via LSP)，不是Crystal或Ruby - 不要装 “Crystal Tools”、“Crystal Language Server” 等第三方替代品——它们已废弃或与新版 LSP 不兼容
用 .crystalconfig 启用 LSP 补全而非依赖 tasks.json
tasks.json 里配 crystal run 只解决“能不能跑”，而 .crystalconfig 才决定“能不能写”。没它，String. 后不会弹出 upcase、split 等方法链补全，悬停也看不到类型签名。
- 在项目根目录新建文件，命名为
.crystalconfig（注意开头是点，无后缀），内容仅一行合法 JSON：{"lsp": true, "auto-reload": true} - 多一个空格、逗号或中文引号都会导致 LSP 启动失败；保存后观察状态栏是否变成
Crystal (via LSP) - 若仍无补全，直接在终端运行
crystal tool lsp --help测试该命令是否可执行；不可执行说明crystal安装损坏或权限不足 - 别指望插件设置页里勾个开关就自动启用语义分析——这是项目级配置，不是全局开关
crystal run 和 crystal build 别混用
两者用途、参数、错误处理机制完全不同。用 tasks.json 配构建任务时，选错命令会导致“报错不跳转”“生成了二进制却没运行”“problemMatcher 失效”等问题。
-
crystal run：解释+编译+执行三合一，适合开发期快速验证；默认不生成文件，错误提示聚焦运行时上下文 -
crystal build：输出原生二进制，适合交付；错误提示更偏向链接与符号解析，problemMatcher 必须匹配crystal build特定格式 - 调试断点不命中？大概率是你在
launch.json里配了crystal build输出的二进制，但没设好program路径或没启用sourceFileMap - 想一键运行又保留调试能力，推荐用
crystal run --debug，它生成带调试信息的临时可执行文件，VSCode 可直接 attach
最常被忽略的其实是 .crystalconfig 文件的合法性校验——它看着简单，但 JSON 语法容错极低，一个隐藏的 BOM 或换行符就能让整个 LSP 静默失败；与其反复重装插件，不如先 cat .crystalconfig | python3 -m json.tool 验证一下。
