• 开发工具

esformatter 是一款开源的 ECMAScript（JavaScript）代码格式化工具，它提供统一的命令行接口，让你轻松实现 VS Code、Vim 保存即格式化，并通过--diff检查模式在 CI 中自动拦截代码风格问题。本文带你从零完成编辑器深度集成与 CI 风格检查的全套配置，让团队代码风格永久保持一致。

🎯 为什么 esformatter 适合编辑器集成？

esformatter 的核心目标是提供细粒度（granular）的空格、缩进和换行控制，并且以命令行工具（CLI）形式交付。这带来几个天然优势：

一句话总结：编辑器负责"改"，CI 负责"查"，两者共用同一份配置，风格问题无处遁形。

📦 esformatter 安装与项目级配置方法

1. 安装 CLI

# 全局安装（编辑器集成推荐） npm install -g esformatter # 或者作为项目 devDependency（保证团队版本一致） npm install --save-dev esformatter

💡 提示：如果项目中本地安装了 esformatter，CLI 会优先使用本地版本而非全局版本。把 esformatter 及所需插件都写进package.json的devDependencies，可以确保团队所有人使用相同版本与插件（见 README.md 的说明）。

2. 配置文件从哪来？

esformatter 从源文件所在目录逐级向上查找并合并配置，直到遇到"root": true为止：

1. 目录下的.esformatter文件（优先级高于同目录的package.json）
2. package.json中的esformatter属性
3. 都没有时，回退到用户全局~/.esformatter

配置查找与合并逻辑见 lib/options.js。

📌 实战建议：在项目根目录的.esformatter中加上"root": true，避免个人全局配置干扰团队规则（官方 protip，见 doc/config.md 的root章节）。

3. 用预设（Preset）快速起步

不想从零调参？内置了default与jquery两个预设（实现分别在 lib/preset/default.js 和 lib/preset/jquery.js）：

esformatter --preset jquery test.js

也可以在新配置中extends预设，再覆盖个别选项：

{ "extends": ["preset:jquery", "./my-rules.json"], "root": true, "indent": { "value": " " } }

预设编写规范详见 doc/presets.md。

常用 CLI 参数速查

完整参数说明见 doc/cli.txt。

💾 VS Code 保存即格式化：esformatter 三步配置

第一步：安装扩展

在扩展市场安装vscode-esformatter扩展（VS Code 官方集成方案，见 README.md 的 Editor integration 章节）。

第二步：写入工作区配置

在项目.vscode/settings.json中启用保存自动格式化：

{ "editor.formatOnSave": true, "[javascript]": { "editor.defaultFormatter": "leftstick.vscode-esformatter" } }

第三步：确认配置生效

保存任意.js文件，VS Code 会在后台调用 esformatter CLI 并以项目内的.esformatter配置完成格式化。

✨ 小贴士：如果希望"保存时只格式化改动部分"，可将"editor.formatOnSaveMode"设为"modifications"，日常编辑体验更顺滑。

⌨️ Vim 保存自动格式化：esformatter 插件配置

官方推荐的 Vim 集成方案是vim-esformatter插件（见 README.md）。配置分两步：

1. 安装插件后，在~/.vimrc中添加自动格式化规则：

" 保存 JS 文件时自动调用 esformatter 格式化 autocmd BufWritePre *.js,*.mjs silent! Esformatter

2. 手动格式化（不保存）：

:Esformatter

这样 Vim 用户与 VS Code 用户共享同一份项目级.esformatter配置，格式结果完全一致——这正是 esformatter 基于 AST 做非破坏性（non-destructive）重排的好处：不会改写代码本身，只调整空格与换行。

🔍 CI 风格检查：用 --diff 退出码拦截格式问题

这是 esformatter 集成中最有价值的部分。当使用--diff检查且发现风格不符时，CLI 会将退出码置为1（逻辑见 lib/cli.js），diff 渲染由 lib/diff.js 完成。任何 CI 系统都能据此判定构建失败。

基础用法

# 检查单个文件或 glob（注意用单引号包裹，避免 shell 提前展开） esformatter --diff 'lib/**/*.js' 'test/*.js' # 输出 unified diff，CI 日志中更易读 esformatter --diff-unified 'src/**/*.js'

退出码为0表示风格全部合规 ✅，非0则说明存在格式问题，流水线应在此失败。

仓库自己的做法（可直接抄作业）

本项目package.json的 lint 脚本就是一个标准的 CI 检查写法（package.json）：

{ "scripts": { "lint": "jshint lib/*.js lib/**/*.js test/*.js && ./bin/esformatter --diff 'lib/**/*.js' 'test/*.js'", "format": "esformatter -i 'lib/**/*.js' 'test/*.js'" } }

可以看到：--diff用于检查，-i用于一键修复，两条命令分工明确。

加一道 pre-commit 前置关卡

在.git/hooks/pre-commit中加一个极简脚本，提交前本地先挡一次：

#!/bin/sh esformatter --diff-unified "$@"

本地先拦一次，CI 少跑一次，反馈快人一步。💪

🧰 实用技巧与常见问题

• glob 忘加引号？务必写成'lib/**/*.js'，否则 shell 会提前展开，文件多时可能报参数过长。
• 个人配置干扰项目？在项目根.esformatter中设"root": true，配置合并立即终止，不再加载父目录与全局配置（见 doc/config.md）。
• 想复用第三方风格？通过plugins或pipe接入其他 CLI 工具（如先跑strip-debug再格式化），配置说明见 doc/config.md 的pipe章节。
• 团队风格统一？把自定义规则封装成esformatter-preset-xxx包，全组extends即可，编写指南见 doc/presets.md。
• 更多选项怎么查？直接阅读 lib/preset/default.js，其中列出了全部可识别的节点类型名。

总结

esformatter 的集成思路非常清晰：一份.esformatter配置 + 一个 CLI，同时服务三类场景——

1. VS Code / Vim 保存即格式化：编辑体验自动化；
2. --diff+ 非零退出码：CI 与 pre-commit 双重拦截；
3. Preset / extends：团队风格一键复用。

配合官方文档 doc/config.md 与 doc/cli.txt，半小时内就能让团队的 JavaScript 代码风格进入"自动巡航"模式。🚀

• 开发工具