.editorconfig
代码规范工具：从“被嫌弃”到“真香”的实战经验分享
在做技术管理这几年，我深刻地体会到一件事：团队写代码的习惯和风格，直接影响项目的长期可维护性和协作效率。而在这其中，代码规范工具（如 Prettier、ESLint、Checkstyle、Spotless 等）扮演了至关重要的角色。它们不是万能的，但用好了，真的能少很多事。
今天我想跟大家分享的，不是那种“教你安装 ESLint 配置文件”的入门教程，而是我们真实项目中踩过的坑、改过的方案，以及最终如何让代码规范工具真正落地、被大家接受并依赖的真实经历。
一、起因：一个“混乱不堪”的前端项目
那是我在一家创业公司负责前端架构升级的第三个月，接手了一个 Vue + TypeScript 的老项目。项目本身已经上线运行两年，业务逻辑相对稳定，但代码风格却让人不敢恭维：
- 混合使用单引号和双引号
- 缩进有 2、4、甚至不统一的情况
- 有些函数用了箭头函数，有些还在用 function 关键字
- 组件命名风格五花八门：PascalCase、kebab-case、甚至 camelCase 混着来
- 最关键的是——没人会去在意这些问题
当时我的第一反应是：“这得上 ESLint + Prettier！”于是我在本地配了一套规则，然后提交了一次大规模的自动格式化 commit……结果你猜怎么着？第二天早上收到好几条 Slack 消息，说“昨晚的 commit 把他们的 PR 合并不了了”。
那次教训让我意识到：想用工具解决风格问题，第一步不是配置工具，而是理解团队和项目的现状。
二、挑战：不止是代码风格，更是文化冲突
那次大范围的格式化之后，我开始反思。我发现我们面临的问题不仅是技术层面的，还有几个更根本的矛盾：
- 历史包袱重：代码量大，旧代码风格多样，难以一次性格式化；
- 开发习惯不同：有人喜欢手动调整缩进，有人直接保存就格式化；
- IDE 差异大：WebStorm 用户和 VSCode 用户对格式化的反馈不一样；
- 规则偏好不一致：到底是 single quote 还是 double quote？该不该强制 semi？
- 工具链整合困难：CI 中如何集成 linting？如何避免每次 push 都报错？
更尴尬的是，团队里有些人觉得这些“格式问题”完全没必要折腾。“又不影响功能”，这是我听到最多的反对理由。
三、解决方案：分阶段推进 + 自动化为主 + 规则透明化
我们采取了以下策略：
1. 先统一 IDE 插件和编辑器配置
我们在 .editorconfig 文件中定义基础格式规则：
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
然后在 VSCode 和 WebStorm 中分别推荐安装 Prettier 插件，并设置成保存时自动格式化。这样确保每个人在本地就能看到修改后的效果，减少了格式差异带来的困扰。
2. 渐进式引入 ESLint/Prettier
没有一开始就跑 full lint 扫描全项目，而是先在 CI 中加了如下命令：
npx eslint --ext .ts,.tsx,.js,.vue src/
同时限制只检查新改动的代码。后来逐步将规则放宽，直到我们可以放心地开启所有校验。
3. 统一规则配置 + 团队投票定标准
为了减少争议，我把常见的风格选项列成一张表格，在周会上请大家投票选择：
| 选项 | 可选值 | 结果 |
|---|---|---|
| 引号类型 | 单引号 / 双引号 | 单引号 ✅ |
| 是否加分号 | 是 / 否 | 否 ✅ |
| 对象属性是否允许末尾逗号 | 是 / 否 | 是 ✅ |
| 缩进大小 | 2 / 4 | 2 ✅ |
这种“民主决策”让大家更有参与感，也减少了对规则的抵触情绪。
4. Git Hooks 做前置校验
我们使用 husky + lint-staged 做 git 提交前的局部检查：
// package.json
"lint-staged": {
"*.{js,jsx,ts,tsx,vue}": [
"prettier --write",
"eslint"
]
}
结合 husky 设置 pre-commit hook：
npx husky add .husky/pre-commit "npx lint-staged"
这样可以确保提交的代码不会违反基本规范。
5. CI 中集成检查流程
最后在 CI 中加入：
# GitHub Action 示例
steps:
- name: Lint & Format Check
run: |
npm run lint
npm run format-check
配合 npm run lint 是执行 ESLint，npm run format-check 是使用 Prettier 校验是否格式正确：
"scripts": {
"lint": "eslint --ext .ts,.tsx,.js,.vue src/",
"format-check": "prettier --check src/**/*.{js,jsx,ts,tsx,vue}"
}
一旦发现未格式化的代码，CI 就会失败，阻止合并。
四、实践示例：我们的 ESLint 配置
这里贴一段我们最终使用的 ESLint 配置片段（以 Vue + TS 为例）：
// .eslintrc.js
module.exports = {
root: true,
env: {
browser: true,
es2021: true,
node: true,
},
extends: [
'eslint:recommended',
'plugin:@typescript-eslint/recommended',
'plugin:vue/vue3-recommended',
'plugin:prettier/recommended',
],
parserOptions: {
ecmaVersion: 2020,
parser: '@typescript-eslint/parser',
sourceType: 'module',
ecmaFeatures: {
jsx: false,
},
},
plugins: ['@typescript-eslint', 'vue'],
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
// Vue 相关
'vue/multi-word-component-names': 0,
'vue/require-default-prop': 0,
'vue/no-unused-components': 1,
// Typescript 推荐规则覆盖
'@typescript-eslint/no-explicit-any': 1,
'@typescript-eslint/ban-ts-comment': 0,
},
};
搭配的 Prettier 配置也非常简单：
// .prettierrc.json
{
"printWidth": 80,
"tabWidth": 2,
"useTabs": false,
"semi": false,
"singleQuote": true,
"trailingComma": "es5",
"bracketSpacing": true,
"arrowParens": "always",
"endOfLine": "auto"
}
五、踩坑经验：那些年我们一起翻过的车
在整个过程中，我们也踩了不少坑，下面分享几个最典型的：
❗️坑一：格式化导致 Git Diff 大爆炸
前面提到过，我刚接手项目那阵子一口气把整个项目跑了 prettier，结果整个仓库的 diff 几乎都是白色空格变化。不仅影响代码 review，还让 Git Blame 完全失效。
✅解决方法：
- 使用 partial formatting：只对变更文件进行格式化
- 使用 lint-staged 实现“增量格式化”
- 对历史遗留代码逐步清理，而不是一次性全修
❗️坑二：VSCode 与 WebStorm 的格式化行为不一致
有的工程师用 VSCode，有的用 WebStorm，默认换行符、缩进处理方式不一致，导致即使开了 Prettier 也会出现格式差异。
✅解决方法：
- 统一配置
.editorconfig - 明确要求在各自 IDE 中开启 Prettier 作为默认 formatter
- 不再依赖 IDE 内建的格式化工具，全部交给 Prettier
❗️坑三：某些老旧项目无法支持 modern ESLint plugin
比如有一个 Angular 项目，版本是 v9，我们想用新的 eslint-plugin-angular 来加强规则，结果发现它只支持 Ivy 架构，需要升级后才行。
✅解决方法：
- 对老旧项目降低检查级别，仅做基本格式化
- 制定迁移计划，逐步将老项目迁移到现代框架标准
- 不强行推新规则，先让工具能用起来再说
六、成效：从抱怨到依赖，代码质量肉眼可见提升
实施规范工具几个月后，我们取得了以下成果：
- Git Diff 更加清晰：只有实际逻辑变动会被标记出来；
- PR Review 效率提高：Reviewers 不用再指出格式问题；
- 新员工快速适应：有了统一规则后，新人可以直接照着模板写；
- 构建稳定性增强：因为格式问题导致的合并冲突大幅下降；
- 代码一致性变高：现在整个项目看起来就像一个人写的！
而且最神奇的是，有一天团队里有人说：“咦，为什么这个文件保存没格式化？”——说明大家已经开始依赖这些工具了。
七、给你的建议：如何让代码规范工具真正“落地”
如果你也在考虑推动代码规范工具落地，或者已经在做了但遇到阻力，以下是我在实践中总结出的一些经验和建议：
✅1. 不要一开始追求“完美规则”，先让它跑起来
很多人纠结每个规则的具体值应该设什么，其实完全可以先用官方推荐配置，等大家都习惯了，再根据实际情况微调。
✅2. 让所有人参与规则制定，哪怕是形式上的投票
哪怕是一些小细节，像“要不要分号”、“是不是单引号”，只要大家参与了决策过程，后续推行就会顺利很多。
✅3. 使用 lint-staged 和 husky 控制“影响范围”
不要一下子修复全量代码，那样会导致大量 diff。可以通过“只修复当前 commit 的文件”来实现渐进式优化。
✅4. 配合 EditorConfig 统一 IDE 行为
别忽视 .editorconfig 这个小文件，它可以有效避免因为个人喜好带来的缩进、换行等问题。
✅5. CI 中设置强校验，防止回退
如果不加 CI 校验，很快你会发现一切努力都会慢慢“松懈”。所以务必在 CI 中强制 lint 检查通过才能合并。
✅6. 遇到阻力不要急，多解释背后的价值
有时候我们会忘记，不是每个人都关心“代码一致性”有多重要。可以用一些例子来类比，比如：
“如果开车的人都靠左行驶，那么大家都不容易撞车；但如果各开各的车道线，那就很容易出事故。”
八、结语：工具只是起点，真正的目标是协作文化
最后我想说的是：工具本身并不是目的。一套规范工具能不能用得好，本质是看你有没有建立起一种“共同维护代码整洁”的文化。
在我现在的团队里，已经形成了一种默契：
- 写完代码顺手保存一次，看看有没有格式警告；
- 提交前记得 check 一下 lint；
- 发现别人代码有风格问题时，不再互相抱怨，而是默默加上一条新 rule；
- 更重要的是：没有人再因为“格式不对”而争论了。
这，才是我最初想看到的样子。
希望这篇文章能帮你少走点弯路，早点让你的团队爱上这套“看似不起眼但超级有用”的代码规范工具链。
如果你也在做类似的事情，欢迎留言交流！一起探讨下你是怎么推动这项工作的 😄
评论 0