Prettier 教程 - JavaScript代码格式化工具

项目概述

Prettier是一个开源的代码格式化工具，用于自动格式化JavaScript、TypeScript、CSS、HTML等多种语言的代码，确保代码风格的一致性和可读性。它通过解析代码并使用自己的规则重新格式化代码，消除了代码风格的争论，让开发者可以专注于代码逻辑。

• 项目链接：https://github.com/prettier/prettier
• 官方网站：https://prettier.io/
• GitHub Stars：47k+

核心概念

1. 格式化：按照预定义的规则重新排列和缩进代码
2. 解析器：将不同语言的代码解析为抽象语法树(AST)
3. 配置：定义Prettier如何格式化代码的设置
4. 忽略文件：指定Prettier应该忽略的文件和目录
5. 插件：扩展Prettier支持的语言和功能
6. 集成：与编辑器、构建工具和CI/CD系统的集成
7. 格式化范围：可以格式化整个文件或特定范围的代码
8. 保存时格式化：在编辑器保存文件时自动格式化代码
9. 命令行工具：通过命令行使用Prettier
10. API：通过编程方式使用Prettier

核心功能

1. 多语言支持：支持JavaScript、TypeScript、CSS、HTML、JSON、Markdown等多种语言
2. 自动格式化：自动调整代码缩进、换行、空格等
3. 一致的代码风格：确保团队代码风格的一致性
4. 可配置性：提供一定程度的配置选项
5. 编辑器集成：与多种编辑器集成，支持保存时格式化
6. 构建工具集成：与Webpack、Gulp等构建工具集成
7. CI/CD集成：在持续集成/持续部署流程中使用
8. 忽略文件：支持忽略特定文件和目录
9. 插件系统：通过插件扩展支持的语言和功能
10. 性能优化：快速格式化大型代码库

安装与设置

基本安装

# 全局安装
npm install -g prettier

# 本地安装（推荐）
npm install --save-dev prettier

# 安装特定版本
npm install --save-dev prettier@2.8.8

基本配置

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "quoteProps": "as-needed",
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

配置文件格式

Prettier支持多种配置文件格式：

1. .prettierrc：JSON格式
2. .prettierrc.json：JSON格式
3. .prettierrc.yml：YAML格式
4. .prettierrc.yaml：YAML格式
5. .prettierrc.js：JavaScript模块格式
6. prettier.config.js：JavaScript模块格式
7. package.json：在package.json中添加prettier字段

基本使用

命令行使用

# 格式化单个文件
npx prettier --write file.js

# 格式化多个文件
npx prettier --write file1.js file2.js

# 格式化目录
npx prettier --write src/

# 格式化整个项目
npx prettier --write .

# 检查文件是否已格式化
npx prettier --check file.js

# 检查目录
npx prettier --check src/

# 检查整个项目
npx prettier --check .

# 查看格式化后的代码（不写入文件）
npx prettier file.js

在编辑器中使用

1. Visual Studio Code：

   • 安装 Prettier - Code formatter 扩展
   • 在设置中启用保存时格式化：

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

2. Sublime Text：

   • 安装 SublimePrettier 插件
   • 配置保存时格式化

3. Atom：

   • 安装 prettier-atom 插件
   • 配置保存时格式化

4. WebStorm：

   • 内置 Prettier 支持，在设置中启用
   • 配置保存时格式化

在构建工具中使用

1. Webpack：

   npm install --save-dev prettier-webpack-plugin

   // webpack.config.js
   const PrettierPlugin = require('prettier-webpack-plugin');
   
   module.exports = {
     // ...
     plugins: [
       new PrettierPlugin({
         tabWidth: 2,
         semi: true,
         singleQuote: true
       }),
     ],
   };

2. Gulp：

   npm install --save-dev gulp-prettier

   // gulpfile.js
   const gulp = require('gulp');
   const prettier = require('gulp-prettier');
   
   gulp.task('format', () => {
     return gulp.src(['src/**/*.js'])
       .pipe(prettier({ singleQuote: true }))
       .pipe(gulp.dest('src/'));
   });

3. npm scripts：

   // package.json
   {
     "scripts": {
       "format": "prettier --write src/",
       "format:check": "prettier --check src/"
     }
   }

API使用

# 安装prettier作为依赖
npm install --save-dev prettier

// 使用API
const prettier = require('prettier');

// 格式化代码
const formattedCode = prettier.format('const foo = {bar: 123};', {
  semi: true,
  singleQuote: true,
  parser: 'babel'
});

console.log(formattedCode);

// 检查代码是否已格式化
const isFormatted = prettier.check('const foo = {bar: 123};', {
  semi: true,
  singleQuote: true,
  parser: 'babel'
});

console.log(isFormatted);

// 获取文件的配置
const config = await prettier.resolveConfig('./src/file.js');
console.log(config);

高级配置

详细配置选项

// .prettierrc
{
  "printWidth": 80,           // 每行最大字符数
  "tabWidth": 2,              // 缩进空格数
  "useTabs": false,           // 是否使用制表符缩进
  "semi": true,               // 是否在语句末尾添加分号
  "singleQuote": false,        // 是否使用单引号
  "quoteProps": "as-needed",  // 对象属性引号使用方式
  "jsxSingleQuote": false,     // JSX中是否使用单引号
  "trailingComma": "es5",     // 尾随逗号使用方式
  "bracketSpacing": true,      // 对象字面量括号之间是否添加空格
  "jsxBracketSameLine": false, // JSX标签闭合括号是否在同一行
  "arrowParens": "avoid",      // 箭头函数参数是否使用括号
  "rangeStart": 0,             // 格式化范围起始位置
  "rangeEnd": Infinity,        // 格式化范围结束位置
  "requirePragma": false,       // 是否需要编译指示
  "insertPragma": false,       // 是否插入编译指示
  "proseWrap": "preserve",    // Markdown文本换行方式
  "htmlWhitespaceSensitivity": "css", // HTML空白敏感度
  "endOfLine": "lf",          // 行结束符
  "embeddedLanguageFormatting": "auto" // 嵌入式语言格式化
}

忽略文件配置

// .prettierignore
# 忽略 node_modules 目录
node_modules/

# 忽略构建输出目录
build/
dist/

# 忽略测试覆盖率目录
coverage/

# 忽略特定文件
*.min.js
*.bundle.js

# 忽略配置文件
.env
.env.local

# 忽略文档
README.md

# 忽略第三方库
third-party/

与ESLint集成

# 安装依赖
npm install --save-dev prettier eslint-plugin-prettier eslint-config-prettier

// .eslintrc.js
module.exports = {
  // ...
  plugins: [
    'prettier'
  ],
  extends: [
    'eslint:recommended',
    'plugin:prettier/recommended'
  ],
  rules: {
    'prettier/prettier': 'error'
  }
};

与TypeScript集成

# 安装依赖
npm install --save-dev prettier typescript

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2
}

使用插件

# 安装插件
npm install --save-dev prettier-plugin-tailwindcss

// .prettierrc
{
  "plugins": ["prettier-plugin-tailwindcss"]
}

编辑器特定配置

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

实用场景

前端项目

功能需求：为前端项目配置Prettier，确保代码格式的一致性。

实现步骤：

1. 安装依赖：

   npm install --save-dev prettier

2. 创建配置文件：

   // .prettierrc
   {
     "semi": true,
     "trailingComma": "es5",
     "singleQuote": true,
     "printWidth": 80,
     "tabWidth": 2
   }

3. 创建忽略文件：

   // .prettierignore
   node_modules/
   build/
   dist/
   coverage/
   *.min.js
   *.bundle.js
   .env
   .env.local

4. 添加npm脚本：

   // package.json
   {
     "scripts": {
       "format": "prettier --write src/",
       "format:check": "prettier --check src/"
     }
   }

5. 编辑器配置：

   • 在VS Code中安装Prettier扩展
   • 配置保存时格式化

React项目

功能需求：为React项目配置Prettier，包括JSX的格式化。

实现步骤：

1. 安装依赖：

   npm install --save-dev prettier

2. 创建配置文件：

   // .prettierrc
   {
     "semi": true,
     "trailingComma": "es5",
     "singleQuote": true,
     "printWidth": 80,
     "tabWidth": 2,
     "jsxSingleQuote": false,
     "jsxBracketSameLine": false
   }

3. 添加npm脚本：

   // package.json
   {
     "scripts": {
       "format": "prettier --write src/",
       "format:check": "prettier --check src/"
     }
   }

4. 与ESLint集成：

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

   // .eslintrc.js
   module.exports = {
     // ...
     plugins: ['prettier'],
     extends: ['plugin:prettier/recommended'],
     rules: {
       'prettier/prettier': 'error'
     }
   };

TypeScript项目

功能需求：为TypeScript项目配置Prettier，确保TypeScript代码的格式化。

实现步骤：

1. 安装依赖：

   npm install --save-dev prettier typescript

2. 创建配置文件：

   // .prettierrc
   {
     "semi": true,
     "trailingComma": "es5",
     "singleQuote": true,
     "printWidth": 80,
     "tabWidth": 2
   }

3. 添加npm脚本：

   // package.json
   {
     "scripts": {
       "format": "prettier --write src/ --ext .ts,.tsx,.js,.jsx",
       "format:check": "prettier --check src/ --ext .ts,.tsx,.js,.jsx"
     }
   }

4. 与tslint集成：

   npm install --save-dev tslint-config-prettier

   // tslint.json
   {
     "extends": [
       "tslint:recommended",
       "tslint-config-prettier"
     ]
   }

多语言项目

功能需求：为包含多种语言的项目配置Prettier，确保所有语言文件的格式化。

实现步骤：

1. 安装依赖：

   npm install --save-dev prettier

2. 创建配置文件：

   // .prettierrc
   {
     "semi": true,
     "trailingComma": "es5",
     "singleQuote": true,
     "printWidth": 80,
     "tabWidth": 2,
     "proseWrap": "preserve",
     "htmlWhitespaceSensitivity": "css"
   }

3. 添加npm脚本：

   // package.json
   {
     "scripts": {
       "format": "prettier --write .",
       "format:check": "prettier --check ."
     }
   }

4. 创建忽略文件：

   // .prettierignore
   node_modules/
   build/
   dist/
   coverage/
   *.min.js
   *.bundle.js
   .env
   .env.local

CI/CD集成

功能需求：在CI/CD流程中集成Prettier，确保所有代码都已格式化。

实现步骤：

1. 安装依赖：

   npm install --save-dev prettier

2. 添加npm脚本：

   // package.json
   {
     "scripts": {
       "format": "prettier --write src/",
       "format:check": "prettier --check src/"
     }
   }

3. 配置CI/CD：

   • GitHub Actions：

     # .github/workflows/format.yml
     name: Code Format
     on: [push, pull_request]
     jobs:
       format:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v2
           - name: Set up Node.js
             uses: actions/setup-node@v2
             with:
               node-version: 16
           - name: Install dependencies
             run: npm install
           - name: Check format
             run: npm run format:check

   • GitLab CI：

     # .gitlab-ci.yml
     format:
       image: node:16
       script:
         - npm install
         - npm run format:check

   • Jenkins：

     # Jenkinsfile
     stage('Format Check') {
       steps {
         sh 'npm install'
         sh 'npm run format:check'
       }
     }

最佳实践

1. 从默认配置开始：使用Prettier的默认配置，然后根据团队需要调整
2. 团队共识：在团队中达成一致的Prettier配置
3. 编辑器集成：在所有编辑器中启用Prettier和保存时格式化
4. CI/CD集成：在CI/CD流程中添加格式化检查
5. 忽略文件：正确配置.prettierignore文件
6. 提交前格式化：使用git hooks在提交前格式化代码
7. 与ESLint集成：使用eslint-config-prettier避免规则冲突
8. 定期格式化：定期运行格式化命令，确保所有代码都已格式化
9. 文档：在项目文档中说明Prettier的使用方法
10. 培训：确保团队成员了解Prettier的使用方法和配置

常见问题与解决方案

1. 与ESLint冲突

问题：Prettier的格式化规则与ESLint的规则冲突

解决方案：

• 安装eslint-config-prettier来禁用与Prettier冲突的ESLint规则
• 使用eslint-plugin-prettier将Prettier作为ESLint规则运行
• 配置ESLint扩展："extends": ["plugin:prettier/recommended"]

2. 格式化速度慢

问题：格式化大型项目时速度慢

解决方案：

• 正确配置.prettierignore文件，忽略不需要格式化的文件
• 使用增量格式化，只格式化修改的文件
• 考虑使用缓存来提高性能
• 对于特别大的文件，可以考虑暂时排除

3. 编辑器集成问题

问题：编辑器中的Prettier集成不工作

解决方案：

• 确保安装了正确的编辑器扩展
• 检查编辑器设置，确保启用了格式化
• 验证项目中是否安装了Prettier
• 检查配置文件是否正确

4. 配置覆盖问题

问题：Prettier似乎没有使用项目的配置

解决方案：

• 确保配置文件位于项目根目录
• 检查配置文件格式是否正确
• 验证配置文件名称是否正确（如.prettierrc）
• 使用prettier --config选项指定配置文件

5. 忽略文件不生效

问题：Prettier没有忽略指定的文件

解决方案：

• 确保.prettierignore文件位于项目根目录
• 检查忽略模式是否正确
• 验证文件路径是否匹配忽略模式
• 使用prettier --ignore-path选项指定忽略文件

6. 特定文件格式化问题

问题：某些文件的格式化结果不符合预期

解决方案：

• 检查文件类型是否被Prettier支持
• 为特定文件类型添加自定义配置
• 考虑使用插件来支持特殊文件类型
• 对于特殊情况，可以使用// prettier-ignore注释

7. 版本兼容性问题

问题：不同版本的Prettier产生不同的格式化结果

解决方案：

• 在package.json中固定Prettier的版本
• 使用npm shrinkwrap或yarn lockfile来锁定依赖版本
• 确保团队成员使用相同版本的Prettier
• 定期更新Prettier到最新版本

8. 与其他格式化工具冲突

问题：Prettier与其他格式化工具（如Stylelint）冲突

解决方案：

• 确保各工具的配置兼容
• 按照正确的顺序运行工具
• 考虑使用统一的配置管理
• 对于CSS文件，可以让Stylelint处理代码质量，Prettier处理格式

9. 性能问题

问题：Prettier在大型项目中运行缓慢

解决方案：

• 正确配置.prettierignore文件
• 使用增量格式化
• 考虑使用缓存
• 对于特别大的文件，可以暂时排除
• 升级到最新版本的Prettier，它通常有性能改进

10. 自定义规则需求

问题：需要Prettier不支持的自定义格式化规则

解决方案：

• 检查是否有插件支持所需的规则
• 考虑使用ESLint或其他工具来强制执行自定义规则
• 向Prettier团队提交功能请求
• 对于特殊情况，可以使用// prettier-ignore注释

与其他格式化工具的比较

Prettier vs ESLint

• 关注点：Prettier专注于代码格式，ESLint专注于代码质量和风格
• 自动修复：两者都支持自动修复，但Prettier更专注于格式修复
• 配置：ESLint配置更复杂，Prettier配置更简单
• 集成：可以一起使用，ESLint负责质量，Prettier负责格式
• 生态系统：两者都有活跃的生态系统

Prettier vs TSLint

• 语言支持：Prettier支持多种语言，TSLint只支持TypeScript
• 关注点：Prettier专注于格式，TSLint专注于TypeScript代码质量
• 维护状态：TSLint已被弃用，推荐使用ESLint与TypeScript插件
• 集成：两者都可以与编辑器和构建工具集成

Prettier vs Stylelint

• 关注点：Prettier专注于格式，Stylelint专注于CSS代码质量
• 语言支持：Prettier支持多种语言，Stylelint只支持CSS相关语言
• 集成：两者都可以与编辑器和构建工具集成
• 协作：可以一起使用，Stylelint负责CSS质量，Prettier负责格式

Prettier vs EditorConfig

• 关注点：Prettier是完整的格式化工具，EditorConfig只是定义基本的编辑器设置
• 配置：Prettier配置更详细，EditorConfig配置更简单
• 集成：EditorConfig被更多编辑器支持，Prettier需要特定扩展
• 协作：可以一起使用，EditorConfig定义基本设置，Prettier处理详细格式化

Prettier vs JSBeautify

• 关注点：两者都是格式化工具，但Prettier更 opinionated
• 配置：JSBeautify提供更多配置选项，Prettier配置更有限
• 生态系统：Prettier有更活跃的生态系统和社区
• 性能：Prettier通常比JSBeautify更快
• 语言支持：Prettier支持更多现代语言和特性

参考资源

1. 官方文档：https://prettier.io/docs/en/
2. GitHub 仓库：https://github.com/prettier/prettier
3. 配置选项：https://prettier.io/docs/en/options.html
4. 编辑器集成：https://prettier.io/docs/en/editors.html
5. API文档：https://prettier.io/docs/en/api.html
6. 常见问题：https://prettier.io/docs/en/faq.html
7. 插件：https://prettier.io/docs/en/plugins.html
8. ESLint集成：https://prettier.io/docs/en/integrating-with-linters.html
9. CI/CD集成：https://prettier.io/docs/en/precommit.html
10. 迁移指南：https://prettier.io/docs/en/migration.html