Gleam VSCode 支持依赖本地 gleam CLI 和合规项目结构：需先安装 gleam（curl | sh 或 Homebrew），确保 gleam --version 可用且在 PATH 中，通过终端启动 VSCode；仅启用官方 gleam-vscode 插件；项目须满足 gleam.toml name 与 src/name.gleam 一致、子模块声明含 pub mod；格式化失败多因语法不完整或超时设置过短。
装 Gleam 插件前先确认 gleam CLI 已就位
VSCode 的 Gleam 支持完全依赖本地 gleam 命令行工具——插件本身不带编译器或 LSP 服务。如果只装插件没装 CLI，你会看到“no gleam binary found”或诊断功能全灰。
- 运行
gleam --version确认已安装（推荐用curl -sSf https://raw.githubusercontent.com/gleam-lang/gleam/main/install.sh | sh安装） - 确保
gleam在$PATH中，VSCode 启动方式要继承系统环境（比如从终端里执行code .，而非桌面图标直启） - macOS 上用 Homebrew 安装后，若用图形方式启动 VSCode，可能需在
~/.zshrc或~/.zprofile中显式导出PATH
gleam-vscode 插件必须启用，且禁用其他冲突语言扩展
官方唯一维护的插件是 gleam-vscode（作者：gleam-lang），它提供语法高亮、LSP 支持（跳转、补全、类型提示）、gleam test 集成和格式化。常见误操作是顺手装了 “Gleam Language Support” 或 “gleam-lang” 等非官方扩展，它们要么已废弃，要么会与 LSP 端口冲突，导致类型检查失效或编辑器卡顿。
- 卸载所有非
gleam-vscode的 Gleam 相关插件 - 插件设置里保持
"gleam.formatOnSave": true和"gleam.enableLsp": true开启（默认即如此） - 项目根目录下若有
gleam.toml，插件会自动识别；没有的话，部分功能（如模块解析）可能退化
类型提示不显示？大概率是 gleam lsp 没跑起来或项目结构不对
Gleam 的类型信息来自后台运行的 gleam lsp 进程，不是静态分析。它需要能正确解析项目依赖树，而 Gleam 项目必须满足严格结构：入口模块名必须匹配包名（如包名 my_app → 入口文件为 src/my_app.gleam），否则 LSP 启动后立即报错退出，VSCode 状态栏显示 “Gleam: stopped”。
- 检查
gleam.toml中name = "xxx"与src/xxx.gleam是否一致 - 运行
gleam lsp手动测试：应输出类似Starting language server...并挂起，而不是立刻返回或报Could not find package manifest - 若项目含子模块（如
src/utils/string.gleam），确保其模块声明为pub mod utils { pub mod string { ... } }，不能漏掉pub mod声明
保存时格式化失败或报错 Failed to format document
Gleam 格式化由 gleam format 命令驱动，它对输入极其敏感：只接受标准输入（stdin）或明确文件路径，且要求文件内容合法 Gleam 语法。常见触发场景是正在编辑未闭合的字符串、括号，或光标停在语法错误行——此时 VSCode 会把当前不完整文本传给格式器，导致崩溃。
- 避免在写一半的
let x = "hello（缺右引号）时按 Ctrl+S - 格式化失败时不强制重试，等修复语法后再保存；可临时关掉
"gleam.formatOnSave": false观察 - 若频繁失败，检查是否全局配置了
"editor.formatOnSaveTimeout": 750过短（默认 750ms），LSP 响应慢时会被中断，建议调至2000
Gleam 的 VSCode 支持看似简单，但每一步都强依赖 CLI 状态和项目结构合规性。最常卡住的地方不是插件装没装，而是 gleam lsp 启动那一刻——它既不报错也不提示，就静默退出，得靠手动跑命令和看 VSCode 输出面板里的 “Gleam” 通道日志才能定位。
