为什么VSCode中的Erlang代码无法格式化？快速设置erlfmt的教程

看不見的法師

发布时间：2025-09-03 12:39:01

437人浏览过

来源于php中文网

原创

要解决VSCode中Erlang代码无法格式化的问题，需确保erlfmt正确安装并配置。首先通过rebar3插件或escript方式安装erlfmt，并验证其在系统PATH中或指定完整路径；然后在VSCode的settings.json中设置"erlang.erlfmtPath"指向erlfmt可执行文件，启用"editor.formatOnSave"并指定Erlang扩展为默认格式化器；最后重启VSCode。若使用rebar3_fmt，应将路径设为"${workspaceFolder}/_build/default/bin/rebar3_fmt"。常见误区包括未独立安装erlfmt、格式化器未正确指定、调用失败无提示等，可通过查看“输出”面板日志排查。进阶技巧包括在项目根目录添加.erlfmt配置文件统一风格，集成erlfmt到Git pre-commit hook强制格式化，以及利用VSCode调试日志定位问题，从而实现高效、一致的代码格式化。

为什么vscode中的erlang代码无法格式化？快速设置erlfmt的教程

VSCode中Erlang代码无法格式化，通常是因为

erlfmt

这个外部工具没有正确安装，或者VSCode的Erlang扩展未能找到并调用它。它不像一些内置语言那样开箱即用，你需要手动引入并配置这个格式化器。

解决方案

要让VSCode里的Erlang代码乖乖听话，实现自动格式化，核心就是正确配置

erlfmt

。这过程其实不复杂，但有些小细节容易被忽略。

安装

erlfmt

：

erlfmt

通常作为

rebar3

插件使用，这是最推荐的方式。在你的项目

rebar.config

文件中添加：

{plugins, [
    {rebar3_fmt, {git, "https://github.com/erlfmt/erlfmt", {branch, "master"}}}
]}.

然后运行

rebar3 compile

，它会自动下载并编译

erlfmt

。如果你想全局安装，或者项目没有

rebar3

，可以尝试通过

escript

安装：

git clone https://github.com/erlfmt/erlfmt.git
cd erlfmt
./rebar3 escriptize
# 将生成的 escript 拷贝到你的PATH路径下，例如：
cp _build/default/bin/erlfmt /usr/local/bin/

确认安装成功，可以在终端运行

erlfmt --version

。

配置 VSCode

settings.json

：打开VSCode的设置（

Ctrl+,

或

Cmd+,

），搜索“Erlang”，或者直接编辑

settings.json

文件。你可能需要添加或修改以下几行：

{
    // 启用保存时格式化，这是一个全局设置，但对Erlang代码尤其重要
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "pgourlain.vscode-erlang", // 确保Erlang扩展是默认格式化器
    "[erlang]": {
        "editor.defaultFormatter": "pgourlain.vscode-erlang",
        "editor.formatOnSave": true
    },
    // 告诉Erlang扩展去哪里找erlfmt
    "erlang.erlfmtPath": "erlfmt", // 如果erlfmt在PATH中，这样即可
    // 如果erlfmt不在PATH中，你需要提供完整路径，例如：
    // "erlang.erlfmtPath": "/usr/local/bin/erlfmt",
    // 或者对于rebar3项目，指向rebar3_fmt的wrapper脚本
    // "erlang.erlfmtPath": "_build/default/bin/rebar3_fmt" // 这取决于你的rebar3_fmt实际生成路径
}

关于

erlang.erlfmtPath

，如果你是用

rebar3_fmt

插件，最保险的做法是让它指向你的项目根目录下的

_build/default/bin/rebar3_fmt

（或者其他

_build

目录下的路径）。如果

erlfmt

是全局安装在

PATH

里的，那么直接写

"erlfmt"

就行了。

重启 VSCode： 很多时候，配置更改需要重启编辑器才能完全生效。保存
```
settings.json
```
后，彻底关闭并重新打开VSCode。

如何确保erlfmt在我的系统路径中正确安装并被VSCode识别？

这真的是个老生常谈的问题，我记得我第一次遇到这问题时，检查了无数遍VSCode设置，最后才发现是

erlfmt

压根没在我的系统路径里。VSCode，或者说大多数IDE，在调用外部工具时，默认都是依赖你的系统

PATH

环境变量。如果你在终端里能直接敲

erlfmt

并看到输出，那恭喜你，它在

PATH

里。如果不能，那问题就出在这里了。

确保

erlfmt

在

PATH

中的方法，取决于你如何安装它。如果你是通过

escriptize

方式安装，并手动

cp

到

/usr/local/bin/

这类目录，那么只要

/usr/local/bin/

在你的

PATH

里，它就应该能被找到。你可以通过

echo $PATH

（Linux/macOS）或

echo %PATH%

（Windows命令行）来查看你的

PATH

。但对于

rebar3_fmt

插件，它通常是项目本地的。这意味着

erlfmt

的执行文件（实际上是

rebar3_fmt

这个wrapper脚本）位于项目的

_build

目录下。在这种情况下，直接让VSCode去

PATH

里找

erlfmt

是行不通的。你需要在

settings.json

里明确指定其完整路径，比如

"erlang.erlfmtPath": "${workspaceFolder}/_build/default/bin/rebar3_fmt"

。

"${workspaceFolder}"

这个变量在这里就显得非常方便，它指向你当前打开的工作区根目录。

还有一个容易被忽略的点是，你打开VSCode的终端环境可能和系统默认终端环境不一样。有时候，你可能在某个特定的shell配置文件（如

.zshrc

.bashrc

）里添加了

PATH

，但VSCode启动时并没有加载这个配置文件，或者加载了一个不同的。这通常发生在GUI启动的VSCode，而不是从命令行启动的VSCode。如果遇到这种情况，尝试从你的终端里输入

code .

来启动VSCode，看看是否能解决问题。这能确保VSCode继承了当前终端的

PATH

。

VSCode Erlang扩展与erlfmt的集成有哪些常见误区？

我见过不少开发者在这个环节卡壳，包括我自己。最常见的误区，我觉得是把Erlang扩展想象成一个“全能包”。实际上，很多语言的VSCode扩展都只是一个“连接器”或者“适配器”，它本身并不包含语言服务器或格式化器，而是提供一个接口，去调用外部的这些工具。对于Erlang来说，这个外部工具就是

erlfmt

。所以，仅仅安装了Erlang扩展是不够的，你必须独立安装

erlfmt

。

Boba.video

AI动漫视频生成器

下载

另一个常见的误区是关于“格式化时机”。很多人开启了

editor.formatOnSave

，但代码依然没格式化。这可能是因为：

默认格式化器没设对：虽然你在
```
[erlang]
```
部分指定了，但全局的
```
editor.defaultFormatter
```
可能被设成了别的，或者根本没设。VSCode在决定用哪个格式化器时，会有一个优先级。确保Erlang扩展被明确指定为Erlang文件的默认格式化器。
erlfmt
调用失败：即使设置了
```
formatOnSave
```
，如果VSCode尝试调用
```
erlfmt
```
时遇到错误（比如路径不对、权限问题、
```
erlfmt
```
本身崩溃），它就会静默失败，代码自然不会被格式化。这时候，你需要查看VSCode的“输出”面板，选择“Erlang Language Server”或“Log (Extension Host)”来看看有没有报错信息。这就像你喊了一个助手去做事，结果助手没来或者半路摔了一跤，你却不知道。
rebar3_fmt
的上下文问题：如果你用的是
```
rebar3_fmt
```
，它需要在
```
rebar3
```
项目的上下文中运行。这意味着如果你只打开了一个Erlang文件，而不是整个
```
rebar3
```
项目目录，
```
rebar3_fmt
```
可能找不到
```
rebar.config
```
，从而无法工作。确保你打开的是项目的根目录。

还有一种情况，虽然不常见，但值得一提：VSCode的工作区设置（

.vscode/settings.json

）会覆盖用户全局设置。如果你在工作区设置里有冲突的配置，可能会导致问题。检查一下项目根目录下的

.vscode

文件夹，看看有没有什么奇怪的设置。

除了基础配置，还有哪些进阶技巧可以优化erlfmt的使用体验？

当基础设置都搞定后，你可能会想让

erlfmt

更符合团队的编码风格，或者更顺手。这里有几个我个人觉得挺有用的进阶技巧：

项目级的
```
.erlfmt
```
配置文件：
```
erlfmt
```
支持一个名为
```
.erlfmt
```
的配置文件，你可以把它放在项目根目录。这个文件允许你定义更细粒度的格式化规则，比如行宽、缩进、是否保留空行等。这对于团队协作非常重要，因为它确保了所有开发者都使用相同的格式化标准，避免了无休止的格式化提交。比如：
```
%% .erlfmt
{max_columns, 100}.
{indent_size, 4}.
{trailing_commas, true}.
{no_doc_comments, false}.
```
这样，你就不必在每个人的VSCode设置里手动调整这些参数，项目一克隆下来，格式化规则就自动生效了。
集成到 Git Pre-commit Hook： 为了强制团队遵循格式化规范，我强烈建议将
```
erlfmt
```
集成到Git的pre-commit hook中。这样，每次提交代码前，Git都会自动运行
```
erlfmt
```
来检查和格式化Erlang文件。如果格式不符合要求，提交就会被阻止。这能有效地避免“格式化大战”和代码风格不一致的问题。你可以使用
```
husky
```
这样的工具来管理Git hooks，或者手动在
```
.git/hooks/pre-commit
```
里写个脚本：
```
#!/bin/sh
# .git/hooks/pre-commit
# 确保rebar3_fmt在你的PATH中，或者提供完整路径
REBAR3_FMT="${workspaceFolder}/_build/default/bin/rebar3_fmt" # 假设这是你的rebar3_fmt路径

git diff --cached --name-only --diff-filter=ACM | grep '\.erl$' | while read FILE; do
    if [ -f "$FILE" ]; then
        echo "Formatting $FILE..."
        "$REBAR3_FMT" "$FILE" || exit 1
        git add "$FILE"
    fi
done
```
（注意：
```
rebar3_fmt
```
通常是格式化并打印到标准输出，你可能需要用
```
rebar3_fmt "$FILE" > "$FILE.tmp" && mv "$FILE.tmp" "$FILE"
```
这样的方式来原地修改文件。）
VSCode 调试日志： 当遇到格式化问题时，不要盲目尝试。打开VSCode的“输出”面板，选择“Erlang Language Server”或“Log (Extension Host)”，这里会记录Erlang扩展在调用
```
erlfmt
```
时发生的所有交互和错误。这些日志是诊断问题的金矿，能告诉你
```
erlfmt
```
是否被调用、调用参数是什么、以及它返回了什么错误信息。很多时候，问题的原因就在这里一目了然。