代码规范工具踩坑记录：从零开始掌握 ESLint

开篇：什么是代码规范工具，它能帮你做什么？

如果你刚开始学编程，可能已经发现一个现象：写出来的代码虽然能跑，但看起来总感觉“怪怪的”。变量命名不统一、缩进混乱、括号位置参差不齐……这些小问题积累起来会让你的代码难以阅读和维护。

这时就需要一个得力助手——代码规范工具。顾名思义，它的作用就是帮助你检查并优化代码风格，让整个项目的代码保持一致性和可读性。

我们今天要讲的就是最受欢迎的 JavaScript/TypeScript 代码规范工具——ESLint。它不仅可以找出你代码中潜在的错误，还可以根据团队约定的规则来提醒你如何写出更清晰、更规范的代码。

别担心你现在是完全的新手！这篇教程将从零开始，用通俗易懂的语言和具体例子，带你一步步掌握 ESLint 的使用，并避开那些新手常见的“坑”。

---

环境准备：搭建属于你的代码规范环境

我们要先准备好开发环境，这样后续才能愉快地练习 ESLint。

步骤一：安装 Node.js 和 npm

1. 访问 Node.js官网，下载并安装 LTS版本（适合大多数用户的稳定版本）。
2. 安装完成后，在终端或命令行输入：

   node -v
   npm -v
   

   如果看到类似 v18.x.x 和 9.x.x 的版本号，说明安装成功了！

⚠️ 新手常见问题：为什么安装后命令无法识别？

可能是安装路径未加入系统环境变量，可以尝试重新安装或查一下是否加入了 PATH。

步骤二：新建一个项目文件夹

1. 创建一个新文件夹，比如叫 eslint-demo：

   mkdir eslint-demo
   cd eslint-demo
   

2. 初始化 npm 项目：

   npm init -y
   

3. 安装 ESLint：

   npm install eslint --save-dev
   

这时候你会看到项目目录下多了个 node_modules 文件夹和一个 package.json 文件，其中 devDependencies 部分包含了 ESLint。

步骤三：创建 ESLint 配置文件

在项目根目录下创建一个 .eslintrc.js 文件（注意以点开头），内容如下：

module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
  ],
  parserOptions: {
    ecmaVersion: 'latest',
  },
  rules: {
  },
};

这个配置文件告诉 ESLint 当前代码运行环境以及使用哪些默认规则。

✅ 现在你的环境就准备好了！接下来进入核心概念的学习。

---

核心概念讲解：让你明白 ESLint 是怎么工作的

为了理解 ESLint 是怎么起作用的，我们需要了解几个基础术语：

1. 规则（Rule）

ESLint 就像一位严格的老师，而每一条规则就是它的评分标准。例如：

• ✅ 变量必须用 const 或 let 声明（不能用 var）
• ✅ 函数名应该用驼峰命名法
• ❌ 不允许出现 console.log

你可以在 .eslintrc.js 中启用或禁用特定规则。

示例：开启 no-console 规则

rules: {
  "no-console": ["error"]
}

现在当你写 console.log('Hello') 时，ESLint 就会报错。

---

2. 插件（Plugin）

有些规则不是内置的，比如你写 React 或 Vue 代码时，需要额外插件才能支持对 JSX 或模板语法的检测。

例如安装 React 插件：

npm install eslint-plugin-react --save-dev

然后在 .eslintrc.js 中添加插件和规则：

plugins: ['react'],
rules: {
  'react/jsx-uses-react': 'error'
}

---

3. 扩展配置（Extends）

很多时候你可以直接使用别人定义好的一组规则，而不必自己一条条设置。这就是所谓的「扩展配置」。

比如你用了 Airbnb 的 JS 规范：

npm install eslint-config-airbnb-base --save-dev

然后在 .eslintrc.js 中引入它：

extends: ['airbnb-base']

这表示你使用的是 Airbnb 的官方推荐规则集。

---

4. 报告等级（Error / Warning）

每个规则可以被设为三种模式：

• "off" 或 0：关闭这条规则
• "warn" 或 1：提示警告，不影响构建
• "error" 或 2：遇到问题就报错，阻止程序运行

示例：

rules: {
  "no-console": ["warn"] // 只提示，不会阻断执行
}

---

5. 快捷命令：让 ESLint 运行起来

在 package.json 中加上一条脚本命令：

"scripts": {
  "lint": "eslint ."
}

然后执行命令就可以检查当前目录所有 js 文件：

npm run lint

如果想让它自动修复部分问题，可以加 --fix 参数：

npm run lint -- --fix

---

实战项目：跟着我一起用 ESLint 来检查并修复一段糟糕的代码

我们来做一个实战练习，看看 ESLint 如何帮助我们提高代码质量。

第一步：创建一个测试文件 bad-code.js：

function sayhello(name){
console.log("Hello, " + name);
}
sayhello("Alice")

这段代码的功能是输出 Hello Alice，但它有几个明显的问题：

• 函数名没有用驼峰命名法
• 没有加分号
• 缩进不规范

---

第二步：启动 ESLint 检查

执行命令：

npm run lint

你会看到类似如下的输出（取决于你目前的规则配置）：

✖ 2 problems
  1  warning  Unexpected console statement       no-console
  2  error    Missing semicolon                semi

---

第三步：修改规则配置

我们现在把规则改得更严格一些，让 ESLint 检查缩进、命名和语句结尾等问题。

更新 .eslintrc.js：

module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
  ],
  parserOptions: {
    ecmaVersion: 'latest',
  },
  rules: {
    "semi": ["error", "always"],
    "indent": ["error", 2],
    "camelcase": ["warn"],
    "no-console": ["warn"]
  },
};

再次运行：

npm run lint

这次输出可能是这样的：

✖ 3 problems
  1  warning  Identifier 'sayhello' is not in camel case    camelcase
  2  warning  Unexpected console statement                  no-console
  3  error    Expected line break before semicolon          semi

---

第四步：按建议修复代码

根据上面的提示，我们来修改 bad-code.js：

function sayHello(name) {
  console.log("Hello, " + name);
}

sayHello("Alice");

再运行一次：

npm run lint

恭喜！这次没有报错了，说明代码符合规范啦！

---

常见问题解答：那些新手常踩的“坑”，这里都替你趟过了

下面是我在教学过程中整理的一些新手最常遇到的问题和解决办法：

---

❓ Q1：为什么我明明写了规则，但 ESLint 却没检查出来？

原因 & 解决方法：

• 检查 .eslintrc.js 是否位于项目根目录；
• 确保配置文件拼写正确，如 rules 要和关键词完全匹配；
• 添加 "parserOptions" 支持最新语法；
• 使用 npx eslint your-file.js --ext .js,.jsx 查看更详细的调试信息。

---

❓ Q2：我的规则好像冲突了，该听谁的？

原因 & 解决方法：

• 多个配置之间可能存在覆盖关系，建议查看 .eslintrc.js 中的 extends 顺序；
• 更靠后的配置项优先级更高；
• 使用 "overrides" 字段单独给某些文件制定不同规则；
• 最简单的做法：从官方预设配置起步，逐步自定义。

---

❓ Q3：为什么某些警告无法自动修复（fix）？

原因 & 解决方法：

• 因为某些规则逻辑复杂（例如变量命名），需要人工判断；
• 查看 ESLint 文档中的“Fixable”字段标识，只有标出的才可以自动修复；
• 解决方案：手动修改 + 使用 IDE 插件辅助。

---

❓ Q4：我想只忽略某个文件怎么办？

方法一：使用 .eslintignore 文件

创建 .eslintignore，在里面写上你想跳过检查的文件或路径：

src/vendor/
public/
*.min.js

方法二：在代码里临时忽略规则

// eslint-disable-next-line no-console
console.log('this will be ignored');

---

❓ Q5：能不能在 VS Code 里实时显示错误？

当然可以！VS Code 有个很强大的 ESLint 插件：

1. 安装 VS Code 扩展 → 搜索 “ESLint” 并安装；
2. 在 VS Code 设置中启用保存自动修复功能（.vscode/settings.json）：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

这样你在编辑器中编写代码时就能实时获得反馈了！

---

学习建议：下一步该怎么走？

学会了基本的 ESLint 用法之后，你已经掌握了提升代码质量的第一步。那么下面是一些学习路线建议，供你继续深入学习：

🔹 入门进阶（1-2周）

• 熟悉更多 ESLint 内置规则（官方文档）
• 学习如何使用 Prettier 与 ESLint 结合，实现格式化+规范双管齐下
• 练习在 React/Vue/TypeScript 项目中使用 ESLint 插件

🔹 中级应用（2-4周）

• 自定义团队共享的 ESLint 配置包
• 探索 ESLint 插件开发（可选）
• 引入 Husky + lint-staged，实现 Git 提交前自动检查代码
• 搭建 CI 流程，自动化执行 lint 脚本

🔹 进阶拓展（长期）

• 学习其他语言的对应工具（Python 的 flake8、Go 的 golangci-lint 等）
• 对接团队协作工具（Slack、GitHub Actions）实现实时报错提醒
• 阅读源码，了解静态分析原理

---

结语：规范不只是限制，更是通向专业之路的垫脚石

刚开始写代码时，很多人会觉得代码规范工具“麻烦”、“啰嗦”，但一旦养成习惯就会发现，它不仅减少了沟通成本，还大大提升了代码可维护性。

这篇文章从零到一教你配置了一个 ESLint 环境，并通过实战告诉你它如何帮助你写出更优雅的代码。希望你能把它应用到自己的项目中，并持续精进。

记住一句话：写代码是给人看的，偶尔给机器跑一跑。
有了代码规范工具，你写下的每一行代码，都会更有温度。

祝你 coding 顺利！