怎么自定义JS代码格式化的缩进和引号规则

一、理解代码格式化的多层协同体系

初次尝试自定义格式化规则的开发者，最常遇到的挫败是：明明在编辑器菜单里改成了单引号，一按保存却又被强制变回双引号；或者自己改成了 2 空格缩进，同事拉取代码格式化后全变成了 4 空格。产生这种现象的根源在于现代前端开发存在多个不同维度的格式化控制层：

• EditorConfig（跨编辑器基线）：依靠 .editorconfig 约束编辑器的基础行为，如敲击 Tab 键时插入几个空格，它不涉及 JavaScript 的语法 AST，因此无法控制引号。
• Prettier（专业格式化工具）：目前前端生态中占统治地位的代码排版引擎。通过解析语法树完全重写代码外观，是自定义缩进宽度（tabWidth）与引号风格（singleQuote）最核心的配置点。
• ESLint（代码质量与风格校验器）：主要负责检查代码潜在逻辑缺陷与规范。虽然早期的 ESLint 带有 indent 和 quotes 规则，但由于其解析逻辑与 Prettier 容易冲突，现代做法是让 ESLint 专注代码质量，将格式排版完全移交给 Prettier。
• VS Code / IDE 插件层：连接工程配置与日常敲代码的桥梁。需要确保编辑器在按下保存时，调用的是项目中的 Prettier 插件，而非编辑器内置的语言服务。

二、使用 Prettier 配置文件定义缩进与引号

由于 Prettier 拥有纯粹、无歧义的格式化逻辑，自定义缩进与引号规则的第一步也是最关键的一步，就是在项目根目录下创建 Prettier 配置文件。

1. 创建配置文件

在项目的根目录（与 package.json 同级）新建一个名为 .prettierrc 或 .prettierrc.json 的文件。

2. 核心配置选项解析

控制缩进与引号的核心字段一共有以下四个：

3. 典型配置示例

以下是一个针对国内前端团队最常用习惯（2 空格缩进 + 单引号 + 行尾分号）的标准 .prettierrc 配置内容：

{
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "jsxSingleQuote": false,
  "semi": true,
  "trailingComma": "es5",
  "printWidth": 100,
  "arrowParens": "avoid"
}

如果你的团队规范要求采用 4 空格缩进 + 双引号，只需要调整其中对应的键值即可：

{
  "tabWidth": 4,
  "useTabs": false,
  "singleQuote": false,
  "jsxSingleQuote": false,
  "semi": true
}

三、落地实施五步走流程

仅写好配置文件还不够，必须将依赖包、IDE 设置与验证机制打通，才能确保每位开发者在日常保存代码时规则自动生效。

步骤 1：本地安装 Prettier 依赖

在工程终端根目录下执行安装命令，将 Prettier 固定在项目依赖中，避免因为不同开发者本地全局安装的 Prettier 版本差异导致格式化结果不一致：

npm install --save-dev prettier

步骤 2：创建忽略文件 .prettierignore

在根目录下创建 .prettierignore，防止构建输出与第三方依赖目录被错误格式化：

node_modules/
dist/
build/
coverage/
.next/

步骤 3：固化 VS Code 自动格式化配置

在工程根目录下创建 .vscode/settings.json 文件并提交至版本库，强制团队所有使用 VS Code 的成员共享同一套行为准则：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

步骤 4：协调 ESLint，解除校验冲突

如果项目中同时运行着 ESLint，ESLint 默认的 indent 或 quotes 规则可能会在 Prettier 格式化后报红。请安装官方推荐的配置插件：

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

在 ESLint 配置文件中引入该配置以关闭所有与排版冲突的规则：

• 针对 ESLint 9+（Flat Config 模式，eslint.config.js）：

  import prettierConfig from 'eslint-config-prettier';
  
  export default [
    // 你的其他规则与插件...
    prettierConfig, // 必须放在最后以覆盖前面可能启用的样式规则
  ];

• 针对传统 Legacy 模式（.eslintrc.js 或 .eslintrc.json）：

  {
    "extends": [
      "eslint:recommended",
      "prettier" // 放在 extends 数组最末位
    ]
  }

步骤 5：验证与全局批处理

完成上述配置后，打开任意 JS 文件输入一段带有双引号和 4 空格缩进的代码，按下保存快捷键（Windows: Ctrl + S，macOS: Cmd + S），代码应立刻自动变换为 2 空格和单引号。你也可以通过 npm script 批量格式化整个项目：

# 检查项目中是否有不符合规则的文件
npx prettier --check "src/**/*.{js,jsx,ts,tsx}"

# 一键修复格式化整个项目的所有文件
npx prettier --write "src/**/*.{js,jsx,ts,tsx}"

四、各工具关键字段横向映射对照

为了让读者彻底弄清不同工具对“缩进”与“引号”的配置名称，下表详细梳理了各技术载体中的对应字段：

配置原则总结：

1. 缩进方面：.editorconfig 负责提供给编辑器最基本的按键反馈（按 Tab 输入几个空格）；.prettierrc 的 tabWidth 负责在保存时执行语法树层级的缩进对齐；二者数值必须保持一致。
2. 引号方面：EditorConfig 完全不参与引号规则；必须完全由 .prettierrc 的 singleQuote 字段统领，ESLint 配合 eslint-config-prettier 禁用自身校验，交由 Prettier 全权判定。

五、常见问题与冲突排查决策树

在实际落地过程中，如果保存后规则依然没有生效，请按照以下决策流程逐步排查：

1. 为什么保存后单引号闪了一下又变回了双引号？

原因：VS Code 内置的 JavaScript 语言服务或者其他插件（如 Beautify、Vetur 等）与 Prettier 发生了竞争，内置格式化器以默认的双引号重新覆盖了文件。

解决方法：在 VS Code 中右键编辑器任意位置，选择【使用...格式化文档】 -> 【配置默认格式化程序】，明确指定为 Prettier - Code formatter。同时检查 .vscode/settings.json 中的 editor.defaultFormatter 是否已正确写入。

2. 为什么保存后代码格式对了，但页面上全是 ESLint 报红？

原因：Prettier 使用了单引号（singleQuote: true），但 ESLint 规则中仍启用了 "quotes": ["error", "double"]，导致格式化器与校验器互相打架。

解决方法：按照上文第四步安装 eslint-config-prettier，将其添加到配置末尾以关闭冲突规则。

3. 团队成员拉取代码后配置不生效？

原因：许多团队只提交了 src/ 代码，把 .prettierrc 或 .vscode/settings.json 遗漏在 .gitignore 中，导致新成员本地缺少统一的格式化触发配置。

解决方法：确保 .prettierrc 与 .vscode/settings.json 正常提交到 Git 仓库，并在项目 package.json 中配置 "scripts": { "format": "prettier --write ." }，方便新成员随时一键校准。

六、总结与推荐实践

自定义 JavaScript 代码格式化的缩进和引号规则并不需要复杂的黑魔法，只要厘清各自工具的边界，就能建立起稳定无感的开发体验：

• 规则唯一源头：将所有缩进空格数（tabWidth）与引号偏好（singleQuote）集中写在项目根目录的 .prettierrc 中。
• 编辑体验保底：配置 .editorconfig 保持缩进基线同步。
• 解除规则打架：使用 eslint-config-prettier 禁用 ESLint 中的重复样式检测。
• 团队自动化：通过 .vscode/settings.json 开启保存自动格式化，告别手动调整排版的繁琐操作。