JS代码格式化后报错怎么办？解决Prettier与ESLint冲突

一、冲突为什么会发生：规则重叠与职责纠缠

很多初学者常误以为 ESLint 和 Prettier 是一类工具，甚至认为只需配置其中一个即可。事实上，二者诞生的初衷有着本质差异：

• ESLint（代码质量检查工具 / Linter）：基于抽象语法树（AST）分析代码逻辑，主要用于捕获未声明变量（no-undef）、声明却未使用的冗余引用（no-unused-vars）、全等比较（eqeqeq）以及不可达代码等潜在运行时 Bug。
• Prettier（代码格式化器 / Code Formatter）：属于强约束性（Opinionated）排版引擎，它会将源码直接解析后重新输出，统一缩进、行宽换行、逗号与括号间距，旨在彻底消灭团队在代码视觉风格上的无谓争论。

之所以产生冲突，是因为早期的 ESLint 同样内置了大量样式化规则（Stylistic Rules），例如要求字符串必须为单引号还是双引号（quotes）、是否强制在行尾添加分号（semi）、以及缩进是 2 空格还是 4 空格（indent）。

当项目中同时开启了 ESLint 的样式规则与 Prettier 时，一旦两者的配置倾向不一致（或者即便利率一致但 AST 解析器断行策略细微不同），就会出现“Prettier 负责整齐排版，ESLint 判定其格式违规”的死锁状态。若在开发工具中同时配置了保存自动格式化与 ESLint 自动修复，两者将在同一毫秒内争夺源码控制权，导致反复震荡。

二、现代解耦方案：eslint-config-prettier

面对两者的冲突，官方与社区沉淀出的最佳实践是：“上帝的归上帝，凯撒的归凯撒”。把代码的美化排版工作完全委托给 Prettier，将 ESLint 中的所有格式化规则彻底关闭，仅保留其审查代码健壮性的能力。

实现这一目标的关键组件即是 eslint-config-prettier。它的内部实现非常纯粹：本质上是一个庞大的规则字典，将 ESLint 核心规则以及各类流行插件中涉及格式排版的规则统一标记为 "off"（或 0）。

三、实操四步法：彻底解决冲突的完整流程

接下来按照标准步骤，从依赖安装、配置注入、编辑器对齐到最终验证，一步步完成工程化落地。

步骤 1：安装官方依赖包

在项目的根目录下打开终端，执行以下命令将其安装为开发依赖：

# 使用 npm
npm install -D eslint-config-prettier

# 或使用 pnpm
pnpm add -D eslint-config-prettier

# 或使用 yarn
yarn add -D eslint-config-prettier

步骤 2：在 ESLint 配置的最末尾注入该规则包

注意：必须置于配置数组或 extends 的最后一项。因为 ESLint 的后序规则会覆盖前序规则，只有放在最后，才能成功压制前面可能引入的 Airbnb、Standard 或官方推荐集里的格式规则。

根据你当前项目采用的 ESLint 版本，配置方式分为两种：

方案 A：ESLint v9+ 现代扁平配置（eslint.config.js / eslint.config.mjs）

import js from "@eslint/js";
import eslintConfigPrettier from "eslint-config-prettier";

export default [
  js.configs.recommended,
  {
    rules: {
      "no-unused-vars": "warn",
      "no-console": "off",
    },
  },
  // 务必放在配置数组的最后一位！
  eslintConfigPrettier,
];

方案 B：ESLint v8 及更早传统配置（.eslintrc.js / .eslintrc.json）

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "prettier" // 务必是 extends 数组的最后一项！
  ],
  "rules": {
    "no-unused-vars": "warn"
    // 切勿在此手动开启 quotes, semi, indent 等排版规则
  }
}

步骤 3：对齐 Prettier 独立配置文件（.prettierrc）

既然排版规则已经完全交由 Prettier 主导，请在项目根目录下创建 .prettierrc 文件（或 .prettierrc.json），明确团队期望的代码格式：

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

步骤 4：配置 VS Code 编辑器保存流水线

为了保证每次按下 Ctrl+S / Cmd+S 时执行的动作清晰不打架，请在项目根目录下的 .vscode/settings.json 中明确分工：

{
  // 1. 指定默认格式化引擎为 Prettier
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  
  // 2. 开启保存文件时自动排版格式化
  "editor.formatOnSave": true,

  // 3. 让 ESLint 仅在保存时修复真实代码质量问题，不参与常规排版
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },

  // 4. 为 JS / TS 针对性指定格式化器（避免被全局其它插件覆盖）
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

四、验证效果与冲突排查自检

完成上述四步后，我们如何确认配置真正生效、且没有任何隐蔽的冲突规则遗漏？

1. 使用 CLI 工具排查残留规则

eslint-config-prettier 自带了一个极其实用的 CLI 检查脚本，能够自动扫描指定源码文件所应用的所有 ESLint 规则，检测是否存在与 Prettier 互斥的项：

# 针对项目中任意一个 js 文件执行校验
npx eslint-config-prettier src/index.js

期望输出结果：

No rules that are unnecessary or conflict with Prettier were found.

如果命令行输出了某些红色的规则名称（例如 quotes 或 @typescript-eslint/indent），说明当前配置依然残留了未被禁用的格式规则，CLI 会清晰指出这些规则在哪个配置文件中被意外启用了。

五、高频踩坑场景与注意事项

六、总结

解决 Prettier 与 ESLint 冲突的本质不是“调和”规则，而是“彻底解耦”：

1. 分工明确：Prettier 全权接管代码排版与外观美化；ESLint 只关心变量定义、逻辑缺陷、最佳实践等代码质量维度。
2. 末尾覆盖：引入 eslint-config-prettier，务必声明在 ESLint 配置的最末位，完全压制一切遗留格式规则。
3. 统一入口：通过 .vscode/settings.json 确保保存时由 Prettier 发起格式化，ESLint 仅提供质量级代码诊断。

完成这套规范后，日常开发中按保存即可瞬间完成代码排版，既拥有 Prettier 带来的整洁与高效，又保留了 ESLint 对代码质量的静默守护。