【ESLint+Prettier】+前端工程化协作：从规范原理到项目落地，统一团队代码风格，自动修复格式与语法问题，避开规则冲突与配置失效坑！

在这里插入图片描述

📑 文章目录

同学们好，我是 Eugene（尤金），一名多年中后台前端开发工程师。

（Eugene 发音 /juːˈdʒiːn/，大家怎么顺口怎么叫就好）

很多前端开发者都会遇到一个瓶颈：

代码能跑，但不够规范；功能能实现，但维护起来特别痛苦；一个人写没问题，一到团队协作就各种混乱、踩坑、返工。

想写出干净、优雅、可维护的专业代码，靠的不是天赋，而是体系化的规范 + 真实实战经验。

这一系列《前端规范实战》，我会用大白话 + 真实业务场景，不讲玄学、不堆理论，只分享能直接落地的规范、标准与避坑指南。

帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。

一、为什么需要 ESLint 和格式化规范？

1.1 你可能遇到过的场景

// 同事A的风格：单引号、无分号、2空格
const foo = 'hello'
const bar = { name: 'test' }

// 同事B的风格：双引号、有分号、4空格
const foo = "hello";
const bar = {
    name: "test"
};

每次合并代码，要么是格式冲突，要么是风格混在一起，可读性和维护成本都会变高。

⬆ 返回目录

1.2 ESLint 和 Prettier 各自做什么？

工具 主要职责 典型规则
ESLint 代码质量、逻辑错误、最佳实践 no-unused-vars、no-console、eqeqeq
Prettier 格式化、风格统一 引号、分号、缩进、换行
  • ESLint：发现并避免潜在错误、规范写法。
  • Prettier：统一格式，让项目看起来像同一个人写的。

实际项目中，通常 ESLint + Prettier 一起用，各负责一部分。

⬆ 返回目录

二、从零搭建 ESLint

2.1 初始化项目并安装 ESLint

# 在项目根目录执行
npm init -y
npm install eslint --save-dev

⬆ 返回目录

2.2 初始化 ESLint 配置

npx eslint --init

会出现交互式配置，大致如下：

  1. How would you like to use ESLint?
    • 选 To check syntax and find problems（检查语法和问题）
  2. What type of modules does your project use?
    • 选 JavaScript modules (import/export)（ES6 模块）
  3. Which framework does your project use?
    • Vue 选 Vue.js，纯 JS 选 None
  4. Does your project use TypeScript?
    • 用 TS 选 Yes，否则 No
  5. Where does your code run?
    • 浏览器选 Browser，Node 选 Node，混合就两个都选
  6. What format do you want your config file to be in?
    • 推荐 JavaScript 或 JSON

⬆ 返回目录

2.3 生成的 .eslintrc.js 示例

module.exports = {
  env: {
    browser: true,   // 浏览器全局变量，如 window、document
    es2021: true,    // 支持 ES2021 语法
    node: true,      // Node.js 全局变量，如 process
  },
  extends: [
    'eslint:recommended',  // ESLint 推荐规则集
    'plugin:vue/vue3-recommended',  // Vue3 推荐规则（如果选了 Vue）
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    // 自定义规则覆盖
  },
};
  • env：声明代码运行环境，避免把 window、process 当成未定义。
  • extends：继承官方或社区规则集，减少重复配置。
  • rules：单独覆盖某条规则。

⬆ 返回目录

三、常用规则说明

3.1 按错误等级理解

值 含义
"off" 或 0 关闭规则
"warn" 或 1 警告，不阻止构建
"error" 或 2 报错，会阻止构建

⬆ 返回目录

3.2 常见规则示例

1）no-unused-vars：未使用的变量
// ❌ 会报错：foo 声明了但未使用
const foo = 'hello';
console.log('world');

// ✅ 正确：要么用上，要么删掉
const foo = 'hello';
console.log(foo);

规则配置示例：

rules: {
  'no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
}

这样 _unused 这种刻意忽略的参数不会被报错。

2）no-console：生产环境禁止 console
// ❌ 生产环境一般不希望有
console.log('debug');

// ✅ 可以用 eslint-disable-next-line 临时关掉
// eslint-disable-next-line no-console
console.log('临时调试');
3）eqeqeq：使用 === 而非 ==
// ❌ 容易出隐式类型转换问题
if (value == null) { }

// ✅ 推荐
if (value === null || value === undefined) { }
4）vue/multi-word-component-names：Vue 组件名至少两个单词
// ❌ 易与原生 HTML 标签混淆
export default {
  name: 'User'
}

// ✅ 推荐
export default {
  name: 'UserProfile'
}
5）no-var：禁止使用 var
// ❌ 作用域容易混乱
var x = 1;
if (true) {
  var x = 2;  // 覆盖外层 x
}

// ✅ 使用 const / let
const x = 1;
if (true) {
  const x = 2;  // 块级作用域
}

⬆ 返回目录

四、ESLint + Prettier 配合使用

4.1 为什么还要用 Prettier？

ESLint 也能做部分格式化（如引号、分号），但：

  • 规则多、配置杂，容易冲突。
  • 格式化并非 ESLint 的核心职责。

Prettier 专注格式化，配置简单、结果一致。二者分工：

  • ESLint：逻辑、质量、最佳实践。
  • Prettier：空格、换行、引号等样式。

⬆ 返回目录

4.2 安装和配置

npm install prettier eslint-config-prettier eslint-plugin-prettier --save-dev
  • eslint-config-prettier：关闭 ESLint 中与 Prettier 冲突的规则。
  • eslint-plugin-prettier：把 Prettier 作为 ESLint 的一条规则运行。

⬆ 返回目录

4.3 配置示例

.eslintrc.js：

module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'plugin:prettier/recommended',  // 必须放在最后，用于覆盖冲突规则
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    'vue/multi-word-component-names': 'warn',
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
  },
};

.prettierrc：


{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80
}

说明：

  • semi: false：不加分号。
  • singleQuote: true：使用单引号。
  • tabWidth: 2：2 空格缩进。
  • trailingComma: "es5"：对象、数组等在 ES5 允许的地方加尾逗号。
  • printWidth: 80：每行最多 80 字符。

⬆ 返回目录

五、自动修复

5.1 命令行修复

# 检查并修复单个文件
npx eslint src/main.js --fix

# 检查并修复整个目录
npx eslint src --fix

# 指定扩展名
npx eslint "src/**/*.{js,vue}" --fix

带 --fix 时，能自动修复的规则会直接改文件。

⬆ 返回目录

5.2 在 package.json 中添加脚本

{
  "scripts": {
    "lint": "eslint src --ext .js,.vue",
    "lint:fix": "eslint src --ext .js,.vue --fix",
    "format": "prettier --write \"src/**/*.{js,vue,css,json}\""
  }
}

日常使用：

npm run lint        # 只检查
npm run lint:fix    # 检查并尝试自动修复
npm run format      # 用 Prettier 格式化

⬆ 返回目录

5.3 保存时自动修复（VSCode）

安装扩展：

  • ESLint
  • Prettier - Code formatter

在 .vscode/settings.json 中配置：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

保存时会：

  1. 用 Prettier 格式化。
  2. 运行 ESLint 并自动修复可修复的问题。

⬆ 返回目录

六、Vue 项目中的完整配置示例

6.1 目录结构

project/
├── .eslintrc.js
├── .prettierrc
├── .prettierignore
├── package.json
└── src/
    └── ...

⬆ 返回目录

6.2 .eslintrc.js

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'plugin:prettier/recommended',
  ],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    parser: require.resolve('@babel/eslint-parser'),
    requireConfigFile: false,
  },
  plugins: ['vue'],
  rules: {
    'vue/multi-word-component-names': 'warn',
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
  },
  overrides: [
    {
      files: ['*.vue'],
      rules: {
        'indent': 'off',  // Vue 单文件组件由 Prettier 处理缩进
      },
    },
  ],
};

⬆ 返回目录

6.3 .prettierignore

node_modules
dist
*.min.js
package-lock.json

⬆ 返回目录

6.4 依赖版本示例

{
  "devDependencies": {
    "eslint": "^8.57.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.3",
    "eslint-plugin-vue": "^9.24.0",
    "prettier": "^3.2.5",
    "@babel/eslint-parser": "^7.24.0"
  }
}

⬆ 返回目录

七、常见坑和解决方案

7.1 Prettier 和 ESLint 规则冲突

现象：同时开启时出现互相“改回去”的情况。

解决：extends 中把 plugin:prettier/recommended 放在最后，用 eslint-config-prettier 关掉冲突规则。

⬆ 返回目录

7.2 Vue 单文件组件解析失败

现象：Parsing error: Unexpected token 等。

解决：确保安装了 vue-eslint-parser 和 eslint-plugin-vue，并在 parserOptions.parser 中正确配置 Babel 解析器。

⬆ 返回目录

7.3 某些目录/文件不想被检查

在 .eslintignore 中配置：

node_modules
dist
public
*.min.js

⬆ 返回目录

7.4 某几行需要临时忽略规则

// 忽略下一行
// eslint-disable-next-line no-console
console.log('调试');

// 忽略整个块
/* eslint-disable no-console */
console.log('a');
console.log('b');
/* eslint-enable no-console */

建议尽量少用，只针对必要场景。

⬆ 返回目录

7.5 团队协作时的版本锁定

把 ESLint、Prettier 等放在 devDependencies，并用 package-lock.json 或 yarn.lock 锁版本，避免不同成员本地版本不一致导致结果不同。

⬆ 返回目录

八、总结

步骤 建议
新项目 一开始就加上 ESLint + Prettier
规则 优先用 extends，少量在 rules 中微调
格式化 Prettier 负责格式，ESLint 负责质量
自动化 配置保存时自动修复 + CI 中跑 lint
团队 统一配置、统一依赖版本、提交前跑 lint

把 ESLint + Prettier 当成团队的基础设施，可以显著减少风格争论和低级错误，把精力放在业务和架构上。如果还有具体规则或报错不清楚，可以把规则名或报错信息贴出来，一起分析。

⬆ 返回目录

🔍 系列模块导航

📝 工程化与协作规范

一、《Vite 工程化实战：alias/env/proxy/ 打包配置全解析，统一项目规范避坑｜工程化与协作规范篇》
二、《前端多环境配置规范：dev/test/pre/prod 环境差异与配置，避免生产环境踩坑｜工程化与协作规范篇》
三、《前端 Git 协作规范实战：commit message + 分支管理 + 合并流程，告别冲突与混乱｜工程化与协作规范篇》
四、《ESLint + Prettier 实战：统一前端代码风格，自动修复语法格式问题｜工程化与协作规范篇》
五、《Element Plus/VXE-Table UI 组件库规范：统一用法实战，避开样式冲突与维护混乱｜工程化与协作规范篇》

👉 跟着系列慢慢学，把技术功底扎扎实实地打牢～

📚 系列总览

前端体系化学习完全体：基础 → 规范 → 架构 → 大厂面试
四套系列、百余篇高质量实战文，从入门到进阶，一站式补齐前端核心能力

每个系列完结后，都会整理成一篇完整导航文并附上直达链接，方便大家按顺序、体系化学习。

全套内容持续更新中，敬请期待～

⬆ 返回目录

技术成长，从来不是比谁写得快，而是比谁写得稳、规范、可维护。

哪怕每次只吃透一条规范，长期下来，差距会非常明显。

后续我会持续更新前端规范、工程化、可维护代码相关实战干货，帮你告别面条代码、维护噩梦，在开发与面试中更有底气。

觉得有用欢迎 点赞 + 收藏 + 关注，不错过每一篇实战内容。

我是 Eugene，与你一起写规范、写优质代码，我们下篇干货见～

# 前端 # vue.js # javascript # 前端框架
Logo
腾讯云开发者社区

腾讯云面向开发者汇聚海量精品云计算使用和开发经验，营造开放的云计算技术生态圈。

更多推荐

终极指南：Flink SQL连接器版本管理从混乱到有序的升级之路

Apache Flink作为流处理领域的佼佼者，其SQL连接器的版本管理一直是开发者面临的核心挑战。本文将系统讲解Flink SQL连接器版本管理的最佳实践，帮助你轻松应对版本兼容性问题，实现从混乱到有序的升级之旅。## 连接器版本管理的常见痛点 😫在Flink应用开发中，连接器版本管理常常让开发者头疼不已。不同版本的连接器可能导致各种兼容性问题，例如API变更、功能差异甚至运行时错误。

avatar 腾讯云开发者社区

Elasticsearch复杂数据类型终极指南：从入门到精通

Elasticsearch作为功能强大的搜索引擎，支持多种复杂数据类型，让开发者能够灵活处理各种结构化和非结构化数据。本文将带你全面了解Elasticsearch中的复杂数据类型，从基础概念到实际应用，助你轻松掌握数据建模的核心技巧。## 内部对象：构建层级化数据结构在Elasticsearch中，对象类型（Object）是最基础的复杂数据类型之一，用于表示具有嵌套关系的数据。例如，我们可

avatar 腾讯云开发者社区

如何快速搭建Neon无服务器PostgreSQL：面向初学者的完整指南

Neon是一款革命性的无服务器PostgreSQL解决方案，它通过分离存储和计算层，实现了自动扩缩容、类代码式数据库分支以及零级扩展能力。本指南将帮助你从零开始搭建Neon开发环境，体验这款创新数据库的强大功能。## 准备工作：环境要求与依赖项在开始搭建Neon环境前，请确保你的系统满足以下要求：- Linux操作系统（推荐Ubuntu 20.04+或Debian 11+）- Git

avatar 腾讯云开发者社区