vscode需opam+dune+ocaml-lsp-server协同及ocaml platform扩展才能获得完整ocaml开发体验；缺任一环将导致类型提示缺失、保存不格式化、跳转失败等问题。
VSCode 本身不支持 OCaml，必须靠 opam + dune + ocaml-lsp-server 三者协同，再配合 OCaml Platform 扩展才能获得完整开发体验。缺任何一环，都会出现“语法高亮有、类型提示无”“保存不格式化”“点击跳转失败”这类典型症状。
opam 和 dune 必须先装好，且 switch 要激活
VSCode 的 OCaml 插件完全依赖本地 shell 环境里的 ocamlc、dune 和 ocaml-lsp-server 可执行文件。如果只装了系统级的 ocaml 包（比如 Ubuntu 的 apt install ocaml），而没走 opam 流程，ocaml-lsp-server 就找不到编译器路径，整个语言服务会静默失效。
- 用
opam init初始化后，务必运行eval $(opam env)——这步不是一次性的，每次新开终端都要执行，否则 VSCode 启动时读不到正确的PATH和OPAM_SWITCH_PREFIX - 推荐创建专用
switch：opam switch create 5.1.0，再opam install dune ocaml-lsp-server ocamlformat utop；不要用systemswitch，它和opam生态脱节 - 验证是否就位：在终端里运行
which dune和which ocaml-lsp-server，两个都必须返回非空路径
OCaml Platform 扩展要配对 LSP 服务路径
新版 OCaml Platform（v2.x+）默认尝试自动发现 ocaml-lsp-server，但 Windows/WSL 下常因路径解析失败而 fallback 到空服务。这时候编辑器里所有类型提示、跳转、补全都不可用，但界面没有任何报错提示。
- 打开 VSCode 设置（Cmd+, 或 Ctrl+,），搜索
ocaml.serverPath - 手动填入绝对路径，例如 WSL 中是
/home/yourname/.opam/5.1.0/bin/ocaml-lsp-server；Windows 原生安装则可能是C:\Users\XXX\.opam\5.1.0\bin\ocaml-lsp-server.exe - 确保
ocaml.sandbox.root指向当前opam switch根目录（即opam var prefix输出的路径），否则 Merlin 无法加载项目依赖
dune-project 文件是类型检查的开关
没有 dune-project，VSCode 就不知道你用的是 dune 构建系统，ocaml-lsp-server 会退化为纯语法检查模式，所有模块依赖、接口签名、跨文件跳转全部失效。
- 哪怕只是写个
hello.ml，也要在同级目录放一个dune-project，内容至少是(lang dune 3.11)（版本号需匹配你装的dune；2026 年主流稳定版是 3.11） - 不要写
(lang dune 3)这种模糊写法——LSP会拒绝解析 - 若项目含多个可执行文件或库，需在对应子目录加
dune文件，例如bin/dune写(executable (public_name hello) (libraries ))
WSL2 下路径和环境变量最容易被忽略
在 Windows 上通过 Remote - WSL 扩展连接 Ubuntu，若项目放在 /mnt/c/ 路径下，ocaml-lsp-server 会因 Windows 路径分隔符和符号链接问题卡住，表现为“正在加载”状态持续数分钟，最终超时。
- 项目必须置于原生 Linux 路径（如
~/workspace/），禁用/mnt/c/或\wsl$路径 - VSCode 启动时不会自动执行 shell 的
~/.zshrc或~/.bashrc，所以eval $(opam env)的结果对编辑器内建终端和语言服务器完全不可见 - 更稳妥的做法：在项目根目录创建
.vscode/settings.json，强制指定ocaml.sandbox类型与switch名称，例如："ocaml.sandbox": {"type":"opam","switch":"5.1.0"}
