VSCode 本身不支持 OCaml，必须靠 opam + dune + ocaml-lsp-server 三者协同，再配合 OCaml Platform 扩展才能获得完整开发体验。缺任何一环，都会出现“语法高亮有、类型提示无”“保存不格式化”“点击跳转失败”这类典型症状。
直接上结论：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 流程，LSP 就找不到编译器路径，整个语言服务会静默失效。
- 用
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.7)（版本号需匹配你装的 dune） - 若项目含多个可执行文件或库，需在对应子目录加
dune文件，例如bin/dune写(executable (public_name hello) (libraries ...)) - 改完
dune文件后，必须运行dune build一次，让 dune 生成_build/default/.merlin，LSP 才能读取到模块拓扑
调试和运行不能靠“一键运行”，得靠终端或 tasks.json
VSCode 没有内置 OCaml 运行按钮。想执行代码，只有两条路：终端手敲命令，或配 tasks.json 把构建逻辑固化下来。后者更可控，也避免因终端环境变量不一致导致构建失败。
- 在项目根目录建
.vscode/tasks.json，内容示例：
{
"version": "2.0.0",
"tasks": [
{
"label": "dune build",
"type": "shell",
"command": "dune build",
"group": "build",
"presentation": { "echo": true, "reveal": "always", "focus": false }
},
{
"label": "dune exec",
"type": "shell",
"command": "dune exec --no-build",
"args": ["--root", ".", "--", "hello"],
"group": "build",
"dependsOn": "dune build"
}
]
}
- 按
Ctrl+Shift+P→ “Tasks: Run Task” → 选dune exec，就能运行bin/hello.ml对应的可执行目标 - 注意：OCaml 没有原生调试器集成，
launch.json配置无效；真要断点调试，得用ocamldebug命令行工具，或靠print_endline+dune build @runtest配合测试驱动
最常被忽略的一点：WSL2 用户必须确认 .wslconfig 里设了足够内存（memory=4GB），否则 dune build 在中等规模项目上会卡死或 OOM —— 这问题不报错，只表现为 VSCode 状态栏一直显示 “Loading…” 却无响应。
