Crystal 在 VSCode 中无法正常运行，主因是 crystal CLI 未正确配置 PATH 或版本低于 1.12.0；需验证终端与 VSCode 内置终端中 which crystal 和 crystal --version 输出一致，且仅启用官方 Crystal Language Support 插件，配合 .crystalconfig 启用 LSP、shards.yml 及 shards install 才能实现完整语义功能。
Crystal 在 VSCode 中跑不起来，八成不是插件问题，而是 crystal 命令本身没进 PATH 或版本太旧——LSP、补全、调试全依赖它，跳过这步直接装插件等于给没引擎的车贴标。
确认 crystal CLI 可用且版本 ≥ 1.12.0
VSCode 的 Crystal 插件不自带编译器，所有语义分析、格式化、跳转都靠 crystal tool lsp 和 crystal tool format 驱动。Mac 用户用 Homebrew 装完必须验证终端和 VSCode 集成终端是否一致：
- 在系统终端运行
which crystal和crystal --version，确认输出 ≥ 1.12.0 - 在 VSCode 内置终端（
Ctrl+`）里重复执行，结果必须完全一致；若显示/usr/bin/crystal或报 command not found，说明 VSCode 没加载你的 shell 初始化文件 - Linux 用户若手动编译安装，需把
crystal/bin加入$PATH，并确保crystal env能正常输出 SDK 路径 - Windows 用户暂不推荐，官方未提供稳定二进制，WSL2 + Ubuntu 是唯一可行路径
只装 crystal-lang 官方扩展，禁用 Ruby 相关插件
社区存在多个 Crystal 扩展，但只有 Crystal Language Support（作者 crystal-lang）是官方维护、内建 LSP 支持、无需额外配 scry 或 crystal-language-server 的方案。其他扩展如 manastech 版已停更，jgaskins 版仅适配旧版 LSP 协议。
- 卸载所有 Ruby 扩展：尤其是
Solargraph、ruby-solargraph、rebornix.ruby，它们会劫持text/ruby语言模式，导致 .cr 文件被错误识别为 Ruby - 安装后重启 VSCode，打开任意
.cr文件，右下角状态栏应显示Crystal (via LSP)，不是Crystal或Ruby - 在
settings.json中显式指定路径："crystal.executablePath": "/opt/homebrew/bin/crystal"（Apple Silicon）或"/usr/local/bin/crystal"（Intel Mac），避免插件自动探测失败
用 .crystalconfig 启用 LSP 补全而非依赖 tasks.json
很多教程教你在 tasks.json 里配 crystal run，但这只是“能跑”，不是“能写”。真正提升编码效率的是 LSP 提供的链式补全（如 Array.new. 弹出 map、select）、符号跳转和悬停文档——这些必须靠项目级配置激活。
- 在项目根目录新建
.crystalconfig，内容仅一行：{"lsp": true, "auto-reload": true} - 不要放在
~/.crystalconfig全局路径，LSP 不读全局配置 - 保存后，在
src/app.cr中输入String.new.，等待 1–2 秒，应出现方法列表；若无反应，检查 VSCode 输出面板中Crystal Language Server标签页是否有Failed to start language server - 禁用插件的自动构建检查（
"crystal.checkOnSave": false），大型项目开启后会卡死编辑器，问题应交由shards build或终端手动触发
调试别碰 crystal debug，用 C/C++ 扩展直连 lldb
crystal debug 是实验性功能，0.40.0+ 虽支持，但 VSCode 的 Crystal Debugger 扩展已近一年无更新，断点常灰掉、变量视图为空。Crystal 编译为原生二进制，lldb（macOS）或 gdb（Linux）才是正解。
- 先装调试器：
brew install lldb（Mac），sudo apt install gdb（Ubuntu） - 装 VSCode 官方
C/C++扩展（ms-vscode.cpptools），它能识别crystal build生成的 DWARF 符号 - 在
.vscode/launch.json中写：{ "version": "0.2.0", "configurations": [{ "name": "Debug Crystal", "type": "cppdbg", "request": "launch", "program": "${workspaceFolder}/bin/my_app", "args": [], "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "lldb" }] } - 先用
crystal build src/app.cr -o bin/my_app生成带调试信息的二进制，再按F5启动——此时可设断点、看寄存器、单步汇编，这才是 Crystal “如 C 般高效”的真实体验
最易被忽略的点：Crystal 的 LSP 功能严重依赖 shards.yml 是否存在及是否已执行 shards install。没有依赖声明时，require "http/server" 悬停不会显示文档，HTTP::Server 也无法跳转到标准库源码——这不是插件 bug，是 LSP 根本没加载对应模块路径。
