hls不工作90%因vscode未启动它：需填绝对路径（如/home/you/.ghcup/bin/haskell-language-server-9.6.4），禁用wrapper；项目根目录须含.cabal或stack.yaml；hls版本必须与ghc --version严格匹配。

HLS 不工作，90% 是因为 VSCode 根本没启动它——不是插件装错了，而是路径没填对、项目结构不识别、GHC 版本不匹配这三件事卡住了。

haskell.serverExecutablePath 必须填绝对路径，不能依赖 wrapper

VSCode 的 Haskell 插件（ID: Haskell.haskell）默认尝试调用 haskell-language-server，但它不识别 haskell-language-server-wrapper，也不自动 fallback 到 .ghcup/bin/ 下的可执行文件。填错就会卡在 “Starting Haskell language server…” 或直接静默降级为仅语法高亮。

• 先确认你实际用的 GHC 版本：ghc --version（例如输出 9.6.4）
• 再查对应 HLS 二进制是否存在：ls ~/.ghcup/bin/haskell-language-server-9.6.4（Linux/macOS）或 dir C:\ghcup\bin\haskell-language-server-9.6.4.exe（Windows）
• 在 VSCode 设置中搜索 haskell.serverExecutablePath，点击 “Edit in settings.json”，填入完整绝对路径，例如：
  "haskell.serverExecutablePath": "/home/you/.ghcup/bin/haskell-language-server-9.6.4"
• 别填 haskell-language-server-wrapper —— 它只是个 shell 脚本调度器，VSCode 的 LSP 客户端不支持
• 改完必须关闭并重新打开整个 VSCode 窗口，仅重载窗口无效（LSP 进程会残留）

项目根目录必须含 .cabal 或 stack.yaml，且要用 Open Folder 打开

HLS 不是全局服务，它按项目启动，且只在识别出标准 Haskell 项目结构时才加载完整功能。单开一个 Main.hs 文件，它就只是个带高亮的文本编辑器。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 常见失效现象：悬停无类型、Ctrl+Click 跳转失败、修改后错误不标红、状态栏一直显示 “Loading…”
• 快速验证是否识别成功：右下角状态栏出现 “HLS ready” 并附带 GHC 版本号；输出面板切换到 “Haskell” 标签页，应有类似 Run entered for haskell-language-server 的日志行
• 若项目为空或只有 .hs 文件，运行 cabal init -n 生成最小 .cabal，或用 stack new myproj 创建标准项目
• 务必用 VSCode 的 “Open Folder”（不是 “Open File”），且确保打开的是含 .cabal 或 stack.yaml 的最外层目录 —— 比如打开 myproj/，而不是 myproj/src/

ghcup install hls 必须指定 GHC 版本，不能只 run install hls

HLS 与 GHC 版本严格绑定。每个 haskell-language-server-X.Y.Z 二进制只兼容对应版本的 GHC。用 ghcup install hls 不加参数，大概率装的是最新版 HLS，但你的项目用的是旧版 GHC，结果就是静默失效：没报错，只有功能全丢。

• 先运行 ghc --version 确认当前 GHC 版本（如 9.6.4）
• 然后显式安装匹配版本：ghcup install hls 9.6.4
• 验证安装是否成功：haskell-language-server-9.6.4 --version 输出末尾应含 ghc-9.6.4
• Windows 用户注意：PowerShell 默认策略禁止脚本执行，需先运行 Set-ExecutionPolicy Bypass -Scope Process -Force，再执行 ghcup 安装命令
• 国内用户务必提前设置中科大镜像：$env:BOOTSTRAP_HASKELL_YAML = 'https://mirrors.ustc.edu.cn/ghcup/ghcup-metadata/ghcup-latest.yaml'（PowerShell）或 ghcup set mirror https://mirrors.ustc.edu.cn/ghcup/（Linux/macOS）

PATH 在 VSCode 终端里有效 ≠ 在 VSCode 主进程里有效

很多人在终端里能跑 haskell-language-server --version，但 VSCode 就是找不到命令。这是因为 VSCode 启动时读取的是登录 shell 的环境（比如 ~/.zshrc），而你可能只在当前终端临时改了 PATH，或者 ghcup 写的环境变量没被 VSCode 加载。

• 判断方法：在 VSCode 集成终端中运行 echo $PATH（Linux/macOS）或 $env:PATH（PowerShell），看输出是否包含 .ghcup/bin
• 若不包含，说明 VSCode 没 source ghcup 的配置文件（如 ~/.ghcup/env）。解决方式是手动把该行加到你的 shell 配置文件末尾，再重启 VSCode
• 更稳的做法是跳过 PATH 依赖，直接在 haskell.serverExecutablePath 填绝对路径 —— 这样不依赖任何环境变量
• macOS 上尤其要注意：用 Homebrew 装的 ghc 和用 ghcup 装的 hls runtime 不互通，混用必失败

最容易被忽略的是三件事叠在一起：填了 wrapper 路径、打开的是子目录、HLS 版本和 GHC 对不上。只要其中一环断了，HLS 就不会真正启动 —— 表面看是“没反应”，其实是压根没跑起来。