跳到主要内容

代码规范总览

代码规范这组内容，关心的从来不只在“括号放哪、分号要不要”。更大的问题其实是：

  • 团队写出来的代码能不能长期读下去
  • 风险写法能不能尽早拦住
  • review 里能不能少掉一半格式争论
  • 保存、提交、CI 这几道关卡能不能接成一条线

如果把目标只理解成“统一风格”，最后通常会把规范做得很窄。能落地的规范链路，至少会分成这几层：

  • ESLint：静态分析、潜在问题、框架规则、团队约定
  • Prettier：格式统一
  • Stylelint：样式层规范和错误检查
  • Biome：一体化的 lint + format 路线
  • 保存、提交与 CI：把规则接进编辑器、Git hooks 和流水线

建议阅读顺序​

  1. ESLint
  2. Prettier
  3. Stylelint
  4. Biome
  5. 保存、提交与 CI

先把分工想清楚​

很多规范项目后面会变得很别扭，不是因为工具不行，而是边界没分清。

ESLint 负责什么​

更适合放在 ESLint 里的，通常是：

  • 未使用变量
  • 风险写法
  • React Hooks 依赖
  • Promise 漏处理
  • 导入顺序和模块边界
  • 团队约定的编码规则

Prettier 负责什么​

更适合放在 Prettier 里的，通常是：

  • 缩进
  • 引号
  • 分号
  • 换行
  • 尾随逗号
  • 长行折叠

Stylelint 负责什么​

更适合放在 Stylelint 里的，通常是：

  • 重复样式
  • 非法 CSS 写法
  • 属性顺序
  • 选择器约束
  • CSS Modules、SCSS、Vue SFC 里的样式规则

Biome 适合放在哪里看​

Biome 更像另一条路线：

  • 不再拆成 ESLint + Prettier 两套主工具
  • 直接用统一工具链接 lint、format、imports
  • 更适合新项目或愿意简化链路的团队

一套更常见的团队落地顺序​

比较稳的推进方式通常不是“一天之内把所有规则拉满”，而是：

  1. 先统一格式化
  2. 再接基础 lint 规则
  3. 再补框架相关规则
  4. 再把保存、提交和 CI 串起来
  5. 最后才考虑更细的团队约束

这样做的好处很直接：

  • 团队阻力更小
  • 改动噪音更少
  • 规则上线后更容易坚持

老项目和新项目的差别​

新项目​

新项目更适合：

  • 直接上统一配置
  • 把保存时自动修复接好
  • 从第一天就接入 pre-commit 和 CI

老项目​

老项目更稳的方式通常是：

  • 先只检查新增文件或核心目录
  • 先接 warning，不急着全量 error
  • 先清格式，再提规则强度
  • 分批收口，而不是一次性全仓大改

一条比较实用的判断​

如果规范做完之后，出现这些情况，通常说明配置方向有点偏：

  • 保存一次，文件被改得面目全非
  • 团队经常在和工具“对着干”
  • CI 总在拦格式，但没有拦住更关键的问题
  • 规则一大堆，但没人说得清哪些最重要

代码规范做得好不好，不是看规则有多少，而是看这套东西能不能长期跑得顺。