代码规范工具入门指南：从混乱到有序的实战经验分享

开篇：为什么我们要谈代码规范？

如果你是一位前端或者全栈开发者，你一定经历过这样的场景：接手一个老项目，看到满屏没有注释、变量名全是a、b、c的代码，函数长度堪比一篇小作文，样式表混乱无序，JSX结构臃肿得让人喘不过气。那一刻，你会不会心里默念一句：“这谁写的？能不能写点人看得懂的代码？”

我曾经就是那个“被骂的人”。2019年的时候，我们团队在做一次重构项目，原本是一个单页应用，后来慢慢变成了多页混合架构，组件复用性几乎为零。当时我负责一部分核心模块的开发，但因为赶进度、没规范、没审查，结果整个项目的代码风格五花八门。有人用单引号，有人用双引号；有人缩进两个空格，有人四个甚至八个；更有甚者，直接把CSS写成内联样式嵌在JS里。

最后上线前测试阶段，问题层出不穷，排查困难重重，团队成员协作效率极低。那次的经历让我意识到：代码不仅仅是写给人看的，也必须让机器运行正确；而更重要的，它要服务于他人——包括未来的你自己。

于是我们开始引入代码规范工具，并逐步建立起一整套自动化校验和修复机制。这篇文章，就来聊聊我是如何从最初的“反骨青年”转变为代码规范的坚定拥护者的。

---

问题描述：从一团乱麻到规范化治理

项目背景

当时的项目是一个中型B端系统，基于React + TypeScript搭建，采用Webpack打包，部署在阿里云上的Node服务端渲染（SSR）架构。项目初期有3个人参与开发，后来逐渐扩展到8人左右，但前期并没有制定明确的编码规范。

遇到的挑战

• 命名不统一：同一个功能模块，有人写fetchData()，有人写loadSomething()，还有人直接写getData()，调用时根本不知道该用哪个。
• 格式混乱：JSX排版参差不齐，有的换行随意，有的根本不换行，阅读体验极差。
• 可维护性差：很多组件重复率高，但因为命名不同或逻辑封装不一致，难以提取公共组件。
• 静态检查缺失：TS虽然已经启用，但很多潜在错误没有被拦截，比如未定义变量、类型推断错误等。
• 提交随意：PR审核形同虚设，没人会去检查格式是否对齐、有没有未使用的变量等问题。

这些问题导致我们在后期集成、测试和维护过程中频频出错，每次合代码就像拆炸弹一样，生怕哪段“祖传代码”突然爆炸。

---

解决方案：从 ESLint 到 Prettier，再加 Git Hook 和 CI 检查

技术选型与权衡

起初我们也尝试过“口头约定+Code Review”的方式来统一风格，但很快发现这种方式效率极低，而且主观性强，容易引发争议。

于是我们开始着手构建一套自动化的代码质量保障体系。目标很明确：

1. 标准化编码风格
2. 提高可读性和可维护性
3. 减少人为错误
4. 提升团队协作效率

最终，我们的技术方案如下：

工具	功能说明
ESLint	JavaScript/TypeScript 语法检查 + 规范校验
Prettier	格式化代码，统一代码风格
Husky + lint-staged	在 git commit 前自动进行 lint 和 format
GitHub Action	CI 中执行 lint 和 format，防止异常提交

这套工具组合目前已经成为业界主流做法，稳定可靠，配置灵活，社区支持好。接下来我会详细讲讲每一步是怎么做的。

---

代码实践：一步步搭建你的代码质量防线

Step 1: 安装基础依赖

npm install eslint prettier eslint-config-prettier eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev

我们使用的是 React + TypeScript 的项目，所以需要额外安装对应的插件。

Step 2: 创建 ESLint 配置文件 .eslintrc.js

// .eslintrc.js
module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier', // 禁用冲突规则
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 2020,
    sourceType: 'module',
  },
  plugins: ['react', '@typescript-eslint'],
  rules: {
    // 自定义一些更严格的规则，例如：
    'no-console': ['warn'], // 控制台输出仅警告而非报错
    '@typescript-eslint/no-explicit-any': 'warn', // 允许 any 类型，但提示
    'prefer-const': 'error', // 强制 const/let 替代 var
    'react/react-in-jsx-scope': 'off', // React 17之后不需要显式导入React
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
};

Step 3: 创建 Prettier 配置文件 .prettierrc

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always"
}

这一部分可以根据团队习惯调整，比如是否使用单引号、缩进多少、末尾是否保留逗号等。

Step 4: 设置 Git Hook 自动格式化 + 校验

我们通过 husky 和 lint-staged 来实现在提交前自动处理代码。

npm install husky lint-staged --save-dev

然后在 package.json 中添加：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"]
  }
}

这样每次 commit 之前都会自动执行 eslint --fix 修复能改的问题，再用 prettier 统一格式。

---

小插曲：一开始我们踩了个坑

有个同事误删了 node_modules/.cache/eslint 缓存目录，结果本地 ESLint 总是报奇怪的错误，比如“找不到某些规则”。

后来才意识到，有些插件（如 @typescript-eslint/eslint-plugin）会缓存配置和规则集。删除缓存后需要重新跑一遍 lint 才能正常恢复。

教训：不要随便删缓存目录，有问题先试试 eslint --no-cache 或者 rm -rf node_modules/.cache/eslint && npm run lint。

---

踩坑经验：这些细节一定要注意！

✅ 使用 eslint-config-prettier 关闭冲突规则

很多人配置完 ESLint 和 Prettier 后发现总是互相冲突，比如缩进、引号、行数限制等问题。

解决方案是在 extends 里加上 'prettier'，并确保安装了 eslint-config-prettier。这个包的作用就是关闭所有与 Prettier 冲突的 ESLint 规则。

🧠 不建议过度依赖 IDE 插件

虽然 VS Code 支持保存时自动格式化，但我们强烈建议不要完全依赖 IDE，而是通过 Git Hook 统一管理。否则很可能出现“我在本地没问题，但 CI 上却报错了”。

⚠️ 某些规则过于严格可能适得其反

比如我们曾一度开启 "strict" 模式下的 ESLint 规则，强制所有变量都要显式声明类型，但实际工作中反而影响效率。

后来改为只设置为 warn 级别，通过 CI 提示而不是直接阻止提交。人性化的规则才能长久执行下去。

---

效果总结：从脏乱差到高效协作的蜕变

在实施这套规范体系之后，整个团队的工作流发生了显著变化：

🔁 PR 更容易Review了

以前代码风格千奇百怪， reviewer 得一边适应每个人的写法，一边挑逻辑错误。而现在大家提交的代码基本是一致的，风格统一了，审查重点自然就集中在逻辑实现上。

💪 Bug 数量明显下降

很多常见的错误（如未定义变量、拼写错误、类型错误等）都被提前拦截，减少了测试阶段才发现问题的情况。

🚀 新人上手更快

新人入职后，不再需要花时间理解各种奇怪的代码风格差异。我们提供了一键格式化脚本，他们只需要关注业务逻辑即可。

📊 数据变化对比（真实项目统计）

指标	实施前	实施后	变化幅度
日均代码错误数	5.2	1.1	↓79%
PR 审核平均耗时	35分钟	15分钟	↓57%
新人熟悉项目周期	10天	3天	↓70%
因格式问题引发的冲突	高频	几乎为0	↓100%

---

经验分享：来自一线的真实建议

🛠 推荐几种实用的小技巧

1. 添加全局脚本命令（package.json）

"scripts": {
  "lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\"",
  "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,css,scss,json}\""
}

这样可以直接跑整个项目的 lint 或格式化任务。

2. 与 CI 结合（GitHub Action 示例）

name: Lint & Format Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm ci
      - run: npm run lint
      - run: npm run format -- --check # 仅检查，不修改文件

这样在 CI 环节也能兜底，确保即使本地漏掉了，CI 也能拦住。

3. 临时关闭某些规则（慎用！）

如果你遇到某个特定文件确实需要临时忽略某些规则，可以这样写：

/* eslint-disable no-unused-vars */
import React from 'react';
/* eslint-enable no-unused-vars */

// 这个组件暂时没用到某个props
function Demo({ unused }) {
  return <div>Demo</div>;
}

当然，这种情况建议尽量配合 TODO 注释说明理由，方便后续追踪。

---

❗️常见误区提醒

• ❌ “ESLint 是浪费时间”

  初期可能觉得麻烦，但长期来看它是帮你养成良好编程习惯的工具，不是阻碍你的绊脚石。

• ❌ “只要格式化工具就够了”

  格式只是表面，真正的代码质量在于逻辑严谨、可读性强。ESLint 才是守护代码质量的核心。

• ❌ “全部开 error，一个都不能错”

  过于严格的规则会导致开发者抵触心理，不利于推进。建议根据实际情况设置 warn/error 等级。

---

结语：写代码不仅是写功能，更是写协作

回想起那段混乱时期，我常常感慨：写代码不是一个人的事，而是一个团队共同努力的结果。工具只是手段，真正关键的是我们是否有意识去建立秩序、尊重他人、也尊重自己的作品。

今天，我们的项目依然每天都在产出大量新代码，但得益于这套规范体系，团队内部几乎不会再因为“谁的代码格式丑”这种事产生争执。取而代之的是更加高效的沟通和协作。

如果你所在的团队还没建立起代码规范机制，不妨从小处入手，先搭起 ESLint 和 Prettier 的架子，再逐步完善 Git Hook 和 CI 流程。你会发现，干净整洁的代码真的会让人心情愉悦，工作效率倍增。

希望这篇文章能帮你在代码规范这条路上少走弯路，愿你和你的团队都能写出优雅、健壮、可维护的好代码。

共勉。💪