如何在 VSCode 中配置运行 Erlang 语言程序

先说一个很多新手容易忽略的要点：VSCode 本身并不能直接运行 Erlang，它只是调用你本地安装好的 erl 和 rebar3。那些“点不动”“跳转灰”“调试失败”的报错，十有八九不是插件没装对，而是环境根本没接上——说白了，就是 erl 在 VSCode 的内置终端里压根跑不起来。

which erl 在 VSCode 终端里必须返回路径

这是整个配置的起点，也是最容易被跳过的验证步骤。按下 Ctrl+` 打开内置终端，依次执行：

• which erl
• which rebar3

如果任一命令返回空或者 command not found，那么请立刻停手，别急着配 launch.json，也别去折腾插件设置。问题通常出在以下场景：

• 从桌面图标启动 VSCode，它继承的是系统登录时的 PATH，并不会加载你在 ~/.zshrc 里添加的 Erlang 路径。
• Windows 上 erl.exe 的路径如果包含中文或空格，BEAM 会启动失败，但错误信息往往只埋在语言服务器的日志里，终端看不到。
• 使用 asdf 管理版本时，如果忘了 asdf reshim erlang，which erl 就找不到软链接目标。

修复方式其实只有一条：让 VSCode 继承正确的 PATH。要么在已经配好环境的终端中执行 code . 来启动 VSCode（这招最推荐），要么直接把 Erlang 的 bin 目录写进 ~/.zshrc（macOS/Linux）或系统环境变量（Windows），然后完全退出 VSCode 再重启。

erlang.erlPath 和 erlang.rebar3Path 必须填绝对路径

即便 which erl 有输出，erlang-ls 语言服务器默认也不会去读取系统 PATH。它只认你在 VSCode 设置里明确写下的那两行路径——而且必须是真实可执行文件的绝对路径：

• erlang.erlPath：填 /usr/local/lib/erlang/bin/erl（macOS/Linux）或 C:Program Fileserl-25.3binerl.exe（Windows）。不能是软链接，不能是 erl.bat，更不能是个目录。
• erlang.rebar3Path：填 /home/you/.local/bin/rebar3 这类真实路径，同样别用符号链接本身。

改完之后，必须彻底重启 VSCode——语言服务器不会热重载。验证方法也很简单：随便打开一个 .erl 文件，看右下角状态栏是否出现 erlang-ls: ready，这才是真正的生效信号。

tasks.json 必须基于 rebar3 编译

VSCode 的“运行”按钮并不会自动帮你编译 Erlang 项目。你必须手动配置 tasks.json，把 rebar3 compile 接进来，否则改完代码直接调试，只会碰上未编译模块的报错。这里给出一个最小可用配置示例：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "rebar3 compile",
      "type": "shell",
      "command": "rebar3 compile",
      "group": "build",
      "problemMatcher": "$erlang"
    }
  ]
}

几个关键点：

• command 必须是完整的可执行命令，不要写成 cd myapp && rebar3 compile——工作区路径由 VSCode 自动处理，硬写 cd 反而容易出问题。
• problemMatcher 设为 "$erlang"，这样编译错误才能被正确解析并跳转到对应行号。
• 如果项目结构是多层嵌套（比如 workspace 根目录下有多个 app），一定要确保 rebar3 的当前工作目录是项目根目录，也就是那个包含 rebar.config 的目录。

调试前必须手动验证 application:ensure_all_started/1

VSCode 调试器本质上只是启动一个带参数的 Erlang 节点再 attach 上去，它并不负责解决依赖缺失。如果你在 launch.json 里写了 "startFun": "application:start", "startArgs": "[myapp]"，但实际项目中 myapp 依赖 cowboy，而 cowboy 又没启动，调试器会直接报 {error,{not_started,cowboy}} 并退出，连断点都设不上。

务必在调试前走通这三步：

• 在项目根目录运行 rebar3 shell。
• 在 shell 里执行 application:ensure_all_started(myapp).，确认返回 ok。
• 检查 startFun 是否匹配真实入口：有些项目用 myapp:start/0，有些用 myapp_app:start/2，函数签名错一个字符就会失败。

这里有个复杂之处：application:ensure_all_started/1 成功并不代表所有模块都已加载，某些模块可能会延迟加载。断点只对已加载模块生效，所以首次调试时，建议先在 shell 里手动 c(my_module).，确保模块已编译并加载。