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 文件，它就只是个带高亮的文本编辑器。
- 常见失效现象：悬停无类型、
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 装的hlsruntime 不互通，混用必失败
最容易被忽略的是三件事叠在一起：填了 wrapper 路径、打开的是子目录、HLS 版本和 GHC 对不上。只要其中一环断了，HLS 就不会真正启动 —— 表面看是“没反应”，其实是压根没跑起来。
