Prettier配置指南：统一代码风格的完整实践-牛站云

一、为什么需要统一代码格式

团队开发中，代码风格不统一是非常常见的问题。有人使用单引号，有人使用双引号；有人习惯在对象属性后保留逗号，有人则完全不保留；换行、缩进、括号空格等细节也可能存在明显差异。

这些问题通常不会直接影响程序运行，却会增加代码审查和维护成本。开发者在提交代码时，经常会因为格式调整产生大量无实际业务意义的 diff。

Prettier 是目前前端项目中使用广泛的代码格式化工具，它通过一套明确的规则自动整理代码，让团队成员在不同编辑器、不同操作系统下也能够保持基本一致的代码风格。

与完全依赖 ESLint 不同，Prettier 更专注于“代码应该如何排版”，例如缩进、换行、引号、尾随逗号等。将 Prettier 与 ESLint 配合使用，可以同时覆盖代码风格和代码质量检查。

二、安装 Prettier

Node.js 项目通常通过 npm 安装 Prettier：

Bash
npm install --save-dev prettier

如果使用 pnpm：

Bash
pnpm add -D prettier

使用 Yarn：

Bash
yarn add --dev prettier

安装完成后，可以通过以下命令确认版本：

Bash
npx prettier --version

也可以直接格式化指定文件：

Bash
npx prettier --write src/index.js

如果希望格式化整个项目，可以执行：

Bash
npx prettier --write .

实际项目中不建议毫无选择地格式化所有目录，应当通过配置文件和忽略文件排除依赖、构建产物以及其他不需要处理的文件。

三、创建 Prettier 配置文件

Prettier 支持多种配置方式，常见做法是在项目根目录创建 .prettierrc：

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

这些配置分别控制不同的代码格式。

1. semi

控制语句末尾是否添加分号：

JSON
{
  "semi": true
}

格式化后的代码：

JavaScript
const name = 'Tom';
console.log(name);

如果设置为：

JSON
{
  "semi": false
}

则会变成：

JavaScript
const name = 'Tom'
console.log(name)

具体采用哪种方式主要取决于团队现有代码规范，关键是项目内部保持一致。

2. singleQuote

控制 JavaScript、TypeScript 等代码中的字符串是否优先使用单引号：

JSON
{
  "singleQuote": true
}

例如：

JavaScript
const message = 'Hello World';

需要注意，singleQuote 并不意味着所有场景都会强制使用单引号。例如 JSON 本身要求使用双引号，因此 .json 文件仍然需要遵循 JSON 语法。

3. tabWidth

控制缩进宽度：

JSON
{
  "tabWidth": 2
}

前端项目通常使用 2 个空格作为一级缩进。

4. useTabs

控制缩进是否使用 Tab：

JSON
{
  "useTabs": false
}

设置为 false 时，Prettier 使用空格进行缩进。

5. trailingComma

控制多行结构中的尾随逗号：

JSON
{
  "trailingComma": "es5"
}

例如：

JavaScript
const user = {
  name: 'Tom',
  age: 18,
};

Prettier 新版本支持 none、es5 和 all 等取值。现代项目如果没有特殊兼容要求，可以根据团队规范选择合适的配置。

6. printWidth

控制代码推荐的最大行宽：

JSON
{
  "printWidth": 100
}

需要注意，printWidth 并不是传统意义上的“绝对最大字符数”。Prettier 会结合语法结构判断是否需要换行。

例如：

JavaScript
const result = someFunction(firstArgument, secondArgument, thirdArgument);

当代码结构较长时，Prettier 可能自动调整成多行形式。

四、推荐的项目级 Prettier 配置

对于常见的 JavaScript、TypeScript、Vue、React 项目，可以从下面的配置开始：

JSON
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all"
}

如果团队希望配置更加明确，可以进一步加入：

JSON
{
  "arrowParens": "always",
  "bracketSpacing": true,
  "endOfLine": "lf",
  "jsxSingleQuote": false
}

例如：

JSON
{
  "arrowParens": "always"
}

会保留单参数箭头函数的括号：

JavaScript
const getName = (user) => user.name;

而不是：

JavaScript
const getName = user => user.name;

统一这些细节后，可以明显减少团队成员之间因为个人编码习惯产生的格式差异。

五、使用 .prettierignore 排除文件

并不是项目中的所有文件都适合交给 Prettier 处理。

可以在项目根目录创建 .prettierignore：


node_modules
dist
build
coverage
.cache
.vscode
.idea
*.min.js
*.map

这样执行：

Bash
npx prettier --write .

时，就不会重复处理这些目录和文件。

如果项目使用了特殊的生成目录，也应该加入 .prettierignore，避免格式化工具修改自动生成的内容。

六、通过 package.json 简化格式化命令

团队项目通常不会要求开发人员每次手动输入完整的 Prettier 命令，可以直接在 package.json 中添加 scripts：

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

执行：

Bash
npm run format

即可自动格式化项目。

而：

Bash
npm run format:check

只检查代码是否符合当前 Prettier 配置，并不会修改文件。

这一命令特别适合放进 CI 流程。如果提交代码没有经过正确格式化，CI 就可以直接发现问题。

七、让 VS Code 保存时自动格式化

如果主要使用 VS Code 开发，可以安装 Prettier 扩展，并将 Prettier 设置为默认格式化工具。

项目中可以创建 .vscode/settings.json：

JSON
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}

这样每次保存文件时，编辑器都会自动执行格式化。

对于 JavaScript 和 TypeScript 项目，还可以进行更细致的配置：

JSON
{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

如果项目包含 Vue 文件：

JSON
{
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

这样可以减少开发者忘记格式化代码的情况。

八、Prettier 与 ESLint 如何配合

Prettier 和 ESLint 的职责并不完全相同。

Prettier 主要负责：

缩进
换行
引号
分号
尾随逗号
括号空格
代码整体排版

ESLint 更关注：

未使用变量
潜在错误
不合理的代码结构
JavaScript/TypeScript 编码规范
特定框架的代码规则

例如：

JavaScript
const name = 'Tom';
console.log(name);

Prettier 主要负责判断代码应该怎样排版，而 ESLint 可以判断变量是否被合理使用、是否违反项目定义的代码规则。

使用 eslint-config-prettier

如果 ESLint 和 Prettier 同时控制同一个格式规则，就可能出现规则冲突。

例如 ESLint 要求单引号，而另一个规则要求双引号，最终就容易出现反复修改的问题。

可以安装：

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

然后在 ESLint 配置中关闭与 Prettier 冲突的格式规则。

对于使用 Flat Config 的项目，可以采用类似方式：

JavaScript
import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  // 其他 ESLint 配置
  eslintConfigPrettier,
];

这样可以让 ESLint 更专注于代码质量，而将格式化工作交给 Prettier。

九、使用 lint-staged 在提交代码前格式化

大型项目中，可以进一步将 Prettier 接入 Git 提交流程。

首先安装：

Bash
npm install --save-dev husky lint-staged

然后配置 lint-staged：

JSON
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,vue,css,scss,json,md}": "prettier --write"
  }
}

这样 Git 提交时，只处理本次修改的文件，而不是重新格式化整个项目。

这种方式特别适合多人协作项目，可以减少“有人提交代码时顺手格式化整个目录”造成的大量无关 diff。

十、解决 Prettier 与项目现有代码冲突

旧项目接入 Prettier 时，经常会遇到一个问题：项目已经存在大量历史代码，而 Prettier 一次性格式化后会产生非常大的 Git diff。

比较稳妥的方式是先确认团队规范，然后统一执行一次格式化，并单独提交这次格式调整。

例如：

Bash
git checkout -b chore/format-project
npm run format
git add .
git commit -m "chore: format project with prettier"

后续业务提交就不应该继续混入大规模格式调整。

如果直接在业务开发过程中第一次执行全项目格式化，很容易导致代码审查困难，也可能让 Git 冲突明显增加。

十一、不同项目的 Prettier 配置策略

Vue 项目

Vue 项目通常涉及：


.vue
.js
.ts
.json
.css
.scss

建议统一配置 Prettier，并通过编辑器对 .vue 文件启用保存格式化。

如果项目还使用 ESLint，应确保 Vue、ESLint 与 Prettier 三者规则没有重复冲突。

React 项目

React 项目通常包含：


.jsx
.tsx
.js
.ts

JSX 属性较多时，Prettier 的自动换行能够明显改善代码可读性。

例如：

JavaScript

  type="primary"
  size="large"
  disabled={loading}
  onClick={handleSubmit}
>
  提交

开发者无需手动决定每个属性应该如何换行。

Node.js 项目

Node.js 项目除了 JavaScript 或 TypeScript 文件外，还可能存在大量 JSON、Markdown、YAML 配置文件。

建议根据项目实际情况决定哪些文件交给 Prettier 处理，而不是简单执行全目录格式化。

十二、团队协作中的配置管理

Prettier 真正发挥作用的关键不是某个人的编辑器配置，而是项目级配置。

建议将以下文件纳入 Git：


.prettierrc
.prettierignore
package.json
package-lock.json

如果使用 pnpm，则对应提交：


pnpm-lock.yaml

这样团队成员安装依赖后，就能够使用同一版本的工具和相同的格式规则。

同时，可以在 package.json 中固定 Prettier 的开发依赖版本，例如：

JSON
{
  "devDependencies": {
    "prettier": "^3.0.0"
  }
}

实际团队项目还应结合锁文件控制依赖解析结果，避免不同开发环境使用完全不同的版本。

十三、如何检查配置是否生效

修改 .prettierrc 后，可以使用：

Bash
npx prettier --check .

如果代码不符合规则，会看到对应文件检查失败。

想查看 Prettier 最终使用了哪些配置，可以执行：

Bash
npx prettier --find-config-path src/index.js

也可以直接格式化某个文件：

Bash
npx prettier src/index.js

该命令会把格式化后的结果输出到终端，不修改原文件，适合排查配置问题。

如果希望直接覆盖文件：

Bash
npx prettier --write src/index.js

十四、常见配置问题排查

1. 配置修改后没有生效

首先确认 .prettierrc 位于项目正确位置，并检查文件名称是否存在拼写问题。

可以运行：

Bash
npx prettier --find-config-path src/index.js

确认当前文件实际读取的是哪个配置。

2. VS Code 使用了错误的格式化工具

如果保存时没有按照 Prettier 格式化，可能是其他扩展抢占了默认 Formatter。

可以检查 VS Code 中当前文件类型对应的：


Default Formatter

并确认选择的是 Prettier。

3. ESLint 和 Prettier 反复修改代码

这种情况通常意味着两套工具存在规则冲突。

建议让 Prettier 专门处理格式，让 ESLint 负责代码质量，并使用 eslint-config-prettier 关闭冲突的格式规则。

4. Git 中出现大量格式变化

如果一次执行 prettier --write . 后出现大量修改，首先确认 .prettierignore 是否配置正确。

对于已经运行多年的项目，还需要评估是否应该进行一次独立的格式化迁移，而不是将格式化和业务需求混在同一个提交中。

十五、适合多数前端项目的基础配置

一个简单、易维护的配置可以写成：

JSON
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

同时配合：


node_modules
dist
build
coverage
.cache
*.min.js
*.map

这样的基础方案已经可以满足大多数前端项目的代码格式化需求。

真正重要的并不是配置项越多越好，而是规则稳定、团队成员统一使用，并且尽量减少个人编辑器配置对项目代码风格的影响。

十六、Prettier 配置实践中的几个原则

第一，项目配置优先于个人习惯。团队已经确定代码规范后，不应该因为某位开发者习惯使用不同格式而频繁修改项目配置。

第二，格式化工具不要承担代码质量检查职责。Prettier 负责排版，ESLint 负责发现潜在问题，两者分工清晰后维护成本更低。

第三，避免把生成文件纳入格式化范围。构建目录、依赖目录、压缩文件和自动生成代码通常应该加入 .prettierignore。

第四，尽量在开发阶段自动完成格式化。保存时格式化、提交前检查以及 CI 检查可以形成完整的代码规范保障链。

第五，配置文件本身也属于项目基础设施。不要只在本地编辑器中配置 Prettier，而应该将核心规则放在项目中，让所有开发者使用相同的标准。

通过合理配置 Prettier，可以把大量机械性的代码排版工作交给工具完成，让开发者更多关注业务逻辑、架构设计和代码质量。对于多人协作的 JavaScript、TypeScript、Vue、React 和 Node.js 项目而言，项目级 Prettier 配置、编辑器自动格式化、ESLint 协作以及 CI 检查结合起来，能够形成稳定且可持续的统一代码风格体系。