代码规范工具踩坑记录：给编程新手的实战指南

CodePoet

2025-06-25 18:34

阅读 276

📌 适合人群：完全零基础的新手开发者，或希望提升代码整洁度与协作能力的同学。

🧭 开篇：为什么我们需要代码规范工具？

你是否遇到过这样的情况：

写完一段代码后，看着自己写的代码都觉得“这是谁写的？”
跟别人一起开发项目时，每个人写代码风格都不一样，读起来像乱码？
每次提交代码前都要手动检查缩进、括号、注释，特别累？

这些问题，其实都可以靠代码规范工具来解决！

🔍 什么是代码规范工具？

通俗地讲，它们就像是你电脑里的“编程辅导员”：

告诉你什么时候用了不该用的变量名
检查你的代码是否符合团队规定（比如换行、空格）
在你保存文件时自动优化格式

常见的工具包括：

ESLint（JavaScript/TypeScript）
Prettier
Black（Python）
EditorConfig

💡 我们的目标：使用 Prettier 和 ESLint 手动搭建一个 JavaScript 项目的代码规范环境，并解决常见的踩坑点！

⚙️ 环境准备：开始前的准备工作

✅ 第一步：安装 Node.js

如果你还没有安装 Node.js，请前往 https://nodejs.org 下载长期支持版（LTS）。

安装完成后，在终端输入以下命令验证是否安装成功：

node -v
npm -v

如果出现类似如下输出，说明安装成功：

v18.16.0
9.5.1

✅ 第二步：创建项目目录

新建一个名为 code-style-tutorial 的文件夹，并进入该目录：

mkdir code-style-tutorial
cd code-style-tutorial

初始化 npm：

npm init -y

你会看到生成了一个 package.json 文件。

✅ 第三步：安装 VS Code（推荐编辑器）

下载地址：https://code.visualstudio.com/

安装后打开 VS Code，设置一个插件——Prettier - Code formatter（用于代码格式化），还有ESLint（用于代码规范检查）。

🧠 核心概念讲解：轻松搞懂几个关键词

我们先来看看两个最重要的角色：

🛠️ ESLint：代码规范检查员

它会告诉你：

❗ 函数名不符合命名规范
❗ 变量声明了但没用到
❗ 使用了不推荐的语法

比如以下代码：

const PI = 3.14;
console.log(PI);

如果我们设置不允许常量命名全部大写（虽然这个例子可能不太合理），ESLint 就会提示错误。

🧹 Prettier：代码美化大师

它主要负责：

自动调整代码缩进和格式
统一括号风格
删除无用空格

例如原始代码：

function hello(name){
return "Hello "+name; }

使用 Prettier 后会变成：

function hello(name) {
  return "Hello " + name;
}

⭐ 两者有什么区别？

工具	功能	是否改变代码内容
ESLint	检查代码是否合规	不修改，只报警告
Prettier	自动美化代码结构	直接修改代码内容

🛠️ 实战项目：一步步建立你的第一个规范系统

现在我们通过一个简单的项目来演示如何配置这些工具。

📦 第一步：安装依赖

在终端执行：

npm install eslint prettier eslint-config-prettier eslint-plugin-prettier --save-dev

解释一下每个包的作用：

eslint：核心规范检查工具
prettier：代码格式化引擎
eslint-config-prettier：关闭 ESLint 中与 Prettier 冲突的规则
eslint-plugin-prettier：将 Prettier 集成到 ESLint 中

📄 第二步：创建配置文件

1. 创建 `.eslintrc.js` 文件（ESLint 规则配置）

// .eslintrc.js
module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: ['eslint:recommended', 'plugin:prettier/recommended'],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    // 示例：不允许 console 语句
    'no-console': ['warn'],
    // 限制缩进为 2 个空格
    indent: ['error', 2],
  },
};

这段配置的意思是：

支持浏览器环境和 ES2021 语法
使用 ESLint 推荐规则，并集成 Prettier
设置缩进为 2 个空格，禁止 console.warn/console.log

2. 创建 `.prettierrc` 文件（Prettier 格式设置）

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

这段配置意思是：

一行最多 80 字符
缩进用 2 个空格
使用单引号 '
结尾加分号 ;
括号中间有空格 { a }

3. 创建 `.editorconfig` 文件（通用格式统一）

# .editorconfig
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

作用是让不同编辑器都能识别相同的格式标准。

🖥️ 第三步：添加测试代码

新建一个文件：test.js

function greet(name){return "Hi,"+name   ;}

greet("Alice")

保存之后你应该看到 VS Code 自动帮你美化成这样：

function greet(name) {
  return "Hi," + name;
}

greet("Alice");

⚙️ 第四步：添加 NPM 脚本

修改 package.json 的 scripts 部分：

"scripts": {
  "lint": "eslint .",
  "format": "prettier --write .",
  "check": "prettier --check ."
}

npm run lint → 检查所有 JS 文件是否有不规范的地方
npm run format → 自动格式化所有 JS 文件
npm run check → 查看哪些文件需要被格式化

✅ 第五步：运行脚本

在终端执行：

npm run lint
npm run format

如果一切正常，你不会看到任何报错，并且 test.js 的格式已经变得干净整洁。

🕳️ 新手常见问题 & 解决方案

以下是我在教学中总结的一些高频踩坑点和对应的解决方案：

❓ 问题 1：VS Code 不自动格式化？

✅ 解决方法：

打开 VS Code 设置（Ctrl + , 或 Cmd + ,）
搜索 Format Document With...
设置默认格式化工具为 Prettier
勾选 Format On Save

❓ 问题 2：ESLint 报红但找不到问题在哪？

✅ 解决方法：

点击 VS Code 左下角的 ESLint 图标，查看具体报错
仔细阅读错误信息，尝试理解含义
如果不想某条规则起作用，可以在 .eslintrc.js 里临时关掉：

rules: {
  'no-console': ['off'], // 关闭控制台警告
}

❓ 问题 3：多个配置文件冲突怎么办？

✅ 解决方法：

检查当前项目中是否存在多个 .eslintrc, .prettierrc, .editorconfig 文件。

可以使用以下命令查看文件结构：

ls -a

删掉多余的配置文件即可。

❓ 问题 4：格式化后代码反而出错了？

✅ 解决方法：

这通常是由于某个工具版本不兼容导致。

解决方案：

升级或降级工具版本
使用统一版本策略（如 npx install-peerdeps --dev eslint-config-airbnb）

🎁 学习建议：下一步你可以学什么？

恭喜你完成了本次入门课程！🎉

接下来推荐你继续学习以下几个方向：

📘 进阶方向一：掌握更多 ESLint 规则配置

参考官方文档：

https://eslint.org/docs/latest/rules/

学习如何自定义规则：

如何禁用某些规则
如何对不同类型文件（如 React JSX）定制规则

🔧 进阶方向二：把规范应用到实际项目中

比如：

在 Vue / React / Node.js 项目中引入 Prettier + ESLint
在 Git 提交前自动校验格式（可以用 Husky + lint-staged）

📈 进阶方向三：了解其他语言的规范工具

Python：Black + Flake8
Java：Checkstyle or SonarLint
CSS/SASS：Stylelint

🧾 总结

我们在这篇文章中学到了：

知识点	内容
什么是代码规范工具	ESLint（检查）、Prettier（美化）
如何创建一个规范环境	安装依赖、配置 `.eslintrc`, `.prettierrc` 等文件
常见问题解答	格式化无效、规则报错等
学习路径建议	自定义规则、整合 Git、跨语言扩展

📚 记住一句话：好代码不是写出来的，而是规范出来的！

继续加油，让你的代码变得更优雅吧 😄！

📌 本文共计约 3220 字，完整覆盖从零开始到实际操作的全流程。如果你觉得有用，欢迎分享给身边刚入门的小伙伴！

标签:面试题挑战工具

最热最新

暂无评论

为你推荐

暂无相关推荐

代码规范工具踩坑记录：给编程新手的实战指南

🧭 开篇：为什么我们需要代码规范工具？

🔍 什么是代码规范工具？

⚙️ 环境准备：开始前的准备工作

✅ 第一步：安装 Node.js

✅ 第二步：创建项目目录

✅ 第三步：安装 VS Code（推荐编辑器）

🧠 核心概念讲解：轻松搞懂几个关键词

🛠️ ESLint：代码规范检查员

🧹 Prettier：代码美化大师

⭐ 两者有什么区别？

🛠️ 实战项目：一步步建立你的第一个规范系统

📦 第一步：安装依赖

📄 第二步：创建配置文件

1. 创建 `.eslintrc.js` 文件（ESLint 规则配置）

2. 创建 `.prettierrc` 文件（Prettier 格式设置）

3. 创建 `.editorconfig` 文件（通用格式统一）

🖥️ 第三步：添加测试代码

⚙️ 第四步：添加 NPM 脚本

✅ 第五步：运行脚本

🕳️ 新手常见问题 & 解决方案

❓ 问题 1：VS Code 不自动格式化？

❓ 问题 2：ESLint 报红但找不到问题在哪？

❓ 问题 3：多个配置文件冲突怎么办？

❓ 问题 4：格式化后代码反而出错了？

🎁 学习建议：下一步你可以学什么？

📘 进阶方向一：掌握更多 ESLint 规则配置

🔧 进阶方向二：把规范应用到实际项目中

📈 进阶方向三：了解其他语言的规范工具

🧾 总结

评论 0

为你推荐

精选内容

代码规范工具踩坑记录：给编程新手的实战指南

🧭 开篇：为什么我们需要代码规范工具？

🔍 什么是代码规范工具？

⚙️ 环境准备：开始前的准备工作

✅ 第一步：安装 Node.js

✅ 第二步：创建项目目录

✅ 第三步：安装 VS Code（推荐编辑器）

🧠 核心概念讲解：轻松搞懂几个关键词

🛠️ ESLint：代码规范检查员

🧹 Prettier：代码美化大师

⭐ 两者有什么区别？

🛠️ 实战项目：一步步建立你的第一个规范系统

📦 第一步：安装依赖

📄 第二步：创建配置文件

1. 创建 .eslintrc.js 文件（ESLint 规则配置）

2. 创建 .prettierrc 文件（Prettier 格式设置）

3. 创建 .editorconfig 文件（通用格式统一）

🖥️ 第三步：添加测试代码

⚙️ 第四步：添加 NPM 脚本

✅ 第五步：运行脚本

🕳️ 新手常见问题 & 解决方案

❓ 问题 1：VS Code 不自动格式化？

❓ 问题 2：ESLint 报红但找不到问题在哪？

❓ 问题 3：多个配置文件冲突怎么办？

❓ 问题 4：格式化后代码反而出错了？

🎁 学习建议：下一步你可以学什么？

📘 进阶方向一：掌握更多 ESLint 规则配置

🔧 进阶方向二：把规范应用到实际项目中

📈 进阶方向三：了解其他语言的规范工具

🧾 总结

评论 0

为你推荐

相关推荐

精选内容

1. 创建 `.eslintrc.js` 文件（ESLint 规则配置）

2. 创建 `.prettierrc` 文件（Prettier 格式设置）

3. 创建 `.editorconfig` 文件（通用格式统一）