代码规范工具踩坑记录：从零开始上手 ESLint
开篇：什么是代码规范工具？
你是不是在写代码的时候，常常遇到这样的情况：
- 同事说我写的代码格式不统一
- 提交代码时被 Git 阻止，因为格式不对
- 看自己以前写的代码总觉得“丑”或“看不懂”
这个时候，代码规范工具就派上用场了！
它就像一个“自动格式审查员”，可以自动检查你的代码是否符合一定的书写规范（比如空格、缩进、变量命名等），还能帮你格式化代码，让整个项目看起来整洁一致。
我们这里以 ESLint 为例进行讲解，它是 JavaScript/TypeScript 最流行的静态分析和代码规范工具之一。
环境准备：搭建基础开发环境
在使用 ESLint 前，我们先确保你的电脑已经安装好以下工具：
第一步：安装 Node.js 和 npm
- 访问 https://nodejs.org
- 下载 LTS 版本并安装
- 打开终端（Windows 用 CMD 或 PowerShell，Mac 用 Terminal）输入：
node -v npm -v - 如果出现版本号说明安装成功
✅ 新手问题：Node.js 和 npm 是啥？
简单来说，Node.js 是一个运行 JavaScript 的平台，npm 是它的包管理器。ESLint 就是通过 npm 安装的。
第二步：安装 VS Code（推荐编辑器）
- 访问 https://code.visualstudio.com 下载并安装
- 安装完成后打开，在左侧插件市场中搜索 “ESLint”
- 安装 “ESLint” 插件（由 Microsoft 提供）
现在我们的开发环境就已经准备好了！
核心概念：ESLint 能做什么？
我们可以把 ESLint 理解为一个“智能语法老师”，它主要做三件事：
| 功能 | 作用描述 |
|---|---|
| 检查代码错误 | 自动发现语法错误或者潜在 bug |
| 规范格式 | 统一缩进、括号位置、变量名风格等 |
| 预防坏习惯 | 避免不推荐的写法（比如 == 替换为 ===） |
常见关键词解释
| 关键词 | 通俗解释 |
|---|---|
| Rule（规则） | ESLint 内置了很多规则，比如不允许使用 var |
| Config（配置） | 你可以决定启用哪些规则，默认有多个预设配置 |
| Plugin（插件） | 有些高级功能需要额外安装插件（比如 React 相关规则） |
🚨 新手常问：我不会选规则怎么办？
不要担心！社区提供了很多现成的配置模板（例如 Airbnb、Google 等），我们可以直接使用，避免从头开始定义所有规则。
实战项目：一步步带你配置 ESLint
接下来我们将创建一个简单的项目，并一步一步配置 ESLint。
第一步：创建项目文件夹
在终端执行以下命令：
mkdir eslint-demo
cd eslint-demo
npm init -y
这样就创建了一个基本的 JavaScript 项目。
第二步：安装 ESLint
继续在终端输入：
npm install eslint --save-dev
这会在项目中添加 ESLint 工具。
第三步：初始化 ESLint 配置
输入：
npx eslint --init
系统会逐步询问你一些问题，比如你使用的框架（可以选择 None）、JavaScript 的模块系统、是否使用 TypeScript 等。
建议选择如下回答（适合初学者）：
- How would you like to use ESLint? 👉 To check syntax and find problems
- What type of modules does your project use? 👉 JavaScript modules (import/export)
- Which framework does your project use? 👉 None
- Does your project use TypeScript? 👉 No
- Where does your code run? 👉 Browser
- What format do you want your config file to be in? 👉 JSON
稍等片刻，你会看到 .eslintrc.json 文件被自动生成。
第四步：写一段有问题的代码来测试 ESLint
新建一个文件 index.js，内容如下：
function sayHello(name){
console.log("Hello, " + name)}
sayHello('Tom')
注意这段代码的问题：
- 缺少分号
- 缩进不正确
- 函数体没有正确的换行和对齐
第五步：运行 ESLint 检查代码
在终端输入：
npx eslint index.js
你会看到类似的输出：
✖ 3 problems
1: function lacks a space after name
2: missing semicolon
3: unexpected console statement
ESLint 成功发现了这些问题！
常见问题解答
问题1：为什么我的 ESLint 没有报错？
可能原因：
- 没有设置足够的规则
- 没有开启“error”级别的检查
- 忽略了一些文件或规则
✅ 解决方法：
编辑 .eslintrc.json 文件，加入：
"rules": {
"no-console": "error"
}
保存后重新运行 ESLint 即可看到效果。
问题2：VS Code 中 ESLint 插件不显示警告？
尝试如下步骤：
- 确保
.eslintrc.json存在且有效 - 在 VS Code 设置中搜索“ESLint”，确认已启用实时检测
- 查看右下角是否有 ESLint 图标（应为绿色）
- 若未生效，重启 VS Code 并重新加载 ESLint 插件
问题3：我想使用别人推荐的规则模板怎么办？
以 Airbnb 的 ES6+ 配置为例：
npm install eslint-config-airbnb-base eslint-plugin-import --save-dev
然后修改 .eslintrc.json：
{
"extends": "airbnb-base"
}
再次运行 ESLint，你会发现更多更严格的规则生效了。
进阶技巧：如何自动格式化代码？
我们还可以结合 Prettier 来实现一键美化代码格式。
步骤：
安装 Prettier 和集成插件：
npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier创建
.prettierrc文件：{ "semi": false, "singleQuote": true }修改
.eslintrc.json：{ "extends": ["eslint:recommended", "plugin:prettier/recommended"] }使用 VS Code 的快捷键（默认为 Ctrl+S / Cmd+S）保存时自动格式化即可。
下一步学习建议
恭喜你完成了第一个 ESLint 实战项目！
如果你有兴趣深入学习，可以按照如下路径继续探索：
初级目标（掌握工具）
- ✅ 学习 ESLint 的自定义规则配置
- ✅ 掌握与 Prettier 的深度整合
- ✅ 在 CI/CD 流程中加入 ESLint 自动检查
中级目标（理解原理）
- ✅ 了解 AST（抽象语法树）的基本概念
- ✅ 自己编写 ESLint 插件或规则
- ✅ 学习 JSParser（如 Babel）的工作机制
高级目标（工程实践）
- ✅ 整合 Husky（Git Hook 工具）防止低质量代码提交
- ✅ 构建团队通用的代码规范模板（Shareable Config）
- ✅ 多语言支持（JSX、Vue、TS 等）
结语：写好代码，从规范开始
良好的代码规范不是束缚，而是提升协作效率和代码质量的重要手段。希望这篇教程能帮助你顺利迈过 ESLint 的门槛，不再对“代码检查”感到畏惧。
记住：每一次“报错”都是成长的机会，愿你在代码的世界里写出既优雅又稳定的程序！
📚 附件参考资源：
- ESLint 官网：https://eslint.org
- Prettier 官网：https://prettier.io
- Airbnb 规则模板：https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base
如需后续练习材料，请留言索取完整 demo 项目打包地址。
评论 0