TypeScript 代码风格：ESLint 与 Prettier 配置

代码风格不一致是团队协作中的常见痛点。有人用单引号，有人用双引号；有人行尾加分号，有人不加。这些分歧看似微小，却会消耗大量 Code Review 时间，甚至引发不必要的争论。

本文将手把手教你配置 ESLint 与 Prettier，让代码风格检查和格式化完全自动化，从根本上解决这些问题。

理解两者的分工

在开始配置之前，需要明确 ESLint 和 Prettier 的职责边界。ESLint 专注于代码质量问题，比如未使用的变量、变量作用域错误、不推荐使用的语法等。Prettier 专注于代码格式问题，比如引号风格、行宽限制、缩进空格数等。两者互补而非替代，缺一不可。

第一步：初始化项目

如果你还没有 TypeScript 项目，先创建一个干净的起步环境。

打开终端，进入目标目录后执行：

mkdir ts-style-demo && cd ts-style-demo
npm init -y

初始化 npm 项目后，安装 TypeScript 作为开发依赖：

npm install typescript --save-dev
npx tsc --init

执行完成后，项目根目录会出现 tsconfig.json 文件，这是 TypeScript 的配置文件。

第二步：安装并配置 ESLint

安装 ESLint 及其依赖

执行以下命令，安装 ESLint 核心包、TypeScript 解析器以及 TypeScript 相关的 ESLint 规则集：

npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

创建 ESLint 配置文件

在项目根目录创建文件 .eslintrc.json，内容如下：

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "warn"
  }
}

这个配置文件中，每个字段的含义如下：

验证 ESLint 是否生效

创建测试文件 src/index.ts：

const message: string = 'Hello TypeScript'

export function greet(name: string): string {
    return message + ', ' + name
}

const unusedVar = 42  // 这行应触发未使用变量警告

运行 ESLint 检查：

npx eslint src/index.ts

如果配置正确，终端会显示未使用变量的错误信息。修改代码移除 unusedVar 后重新运行，错误消失说明 ESLint 工作正常。

第三步：安装并配置 Prettier

安装 Prettier

执行以下命令，将 Prettier 安装为开发依赖：

npm install prettier --save-dev

创建 Prettier 配置文件

在项目根目录创建文件 .prettierrc.json，内容如下：

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

各项配置的解释如下：

验证 Prettier 是否生效

继续编辑 src/index.ts，故意制造格式混乱：

const message:string='Hello TypeScript'

export function greet(name:string):string{
  return message+', '+name
}

运行 Prettier 格式化：

npx prettier --write src/index.ts

执行后文件被自动格式化为规范样式，说明 Prettier 配置成功。

第四步：解决 ESLint 与 Prettier 的冲突

直接混用 ESLint 和 Prettier 会产生冲突，因为 ESLint 本身也具备部分格式检查功能（比如引号风格），这与 Prettier 的规则可能不一致。需要安装专门插件来关闭 ESLint 中与 Prettier 冲突的规则。

安装兼容插件

执行以下命令：

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

更新 ESLint 配置文件

修改 .eslintrc.json，在 extends 数组末尾添加两项配置：

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module",
    "project": "./tsconfig.json"
  },
  "plugins": ["@typescript-eslint", "prettier"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "prettier"
  ],
  "rules": {
    "prettier/prettier": "error",
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "warn"
  }
}

新增的 "prettier" 会关闭所有与 Prettier 规则冲突的 ESLint 规则，而 "prettier/prettier": "error" 会将格式问题提升为 ESLint 错误。

联合验证

运行 ESLint：

npx eslint src/index.ts --fix

--fix 参数会自动修复所有可自动修复的问题，包括 Prettier 相关的格式错误。修复完成后，ESLint 和 Prettier 的规则达成一致，不会再出现相互矛盾的情况。

第五步：配置 Git Hooks（可选但推荐）

代码提交前自动检查，可以避免不合规范的代码进入版本库。需要借助 Husky 和 lint-staged 这两个工具。

安装相关依赖

执行以下命令：

npm install husky lint-staged --save-dev

初始化 Husky

执行命令：

npx husky install

这个命令会在 .husky 目录下创建 Git Hooks 的基础设施。

配置 pre-commit 钩子

创建钩子文件：

npx husky add .husky/pre-commit "npx lint-staged"

配置 lint-staged

在 package.json 中添加 lint-staged 配置：

{
  "lint-staged": {
    "*.ts": ["eslint --fix", "prettier --write"]
  }
}

这个配置表示：对所有 .ts 文件，先运行 ESLint 自动修复，再运行 Prettier 格式化，确保提交前的代码同时满足两套规则。

验证 Git Hooks 效果

尝试提交代码：

git add .
git commit -m "Add ESLint and Prettier configuration"

如果在提交过程中出现 ESLint 错误，提交会被阻止，你需要先修复错误才能完成提交。这确保了仓库中的代码始终保持规范。

第六步：IDE 集成配置

命令行工具虽然强大，但日常开发中直接在编辑器中看到问题更高效。以 VS Code 为例进行配置。

安装 VS Code 插件

打开扩展面板，搜索并安装以下插件：

• ESLint（作者 Dirk Baeumer）
• Prettier - Code formatter（作者 Prettier）

配置保存时自动修复

打开 VS Code 设置（Ctrl + ,），搜索 format on save，勾选 Editor: Format On Save 选项。

搜索 eslint auto fix on save，确保以下选项被勾选：

• ESLint: Auto Fix On Save
• ESLint: Format Enable

保存文件时，ESLint 和 Prettier 会自动执行，代码瞬间变为规范格式。

为项目创建工作区设置（推荐）

在项目根目录创建 .vscode/settings.json 文件：

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": ["typescript"]
}

这个文件提交到 Git 后，团队成员使用 VS Code 时会自动获得统一的保存时格式化行为。

常见问题排查

问题一：ESLint 报告 "parserOptions.project" has been set for @typescript-eslint/parser，但 TypeScript 解析器无法正确解析

这通常是因为 tsconfig.json 中的 include 字段没有包含被检查的文件。检查并修正 tsconfig.json 的 include 配置，确保所有需要检查的文件路径都在其中。

问题二：Prettier 和 ESLint 的规则不一致导致循环修复

确保按照本文第四步正确安装了 eslint-config-prettier 并将其添加到 extends 数组的最后位置。如果 eslint-plugin-prettier 的规则优先级不对，可能导致无限循环。

问题三：Git Hooks 没有执行

首先确认 npx husky install 已在当前仓库中成功执行。然后检查 .husky/pre-commit 文件是否有执行权限。如果没有，执行 chmod +x .husky/pre-commit 赋予权限。

总结

配置完成后，你的 TypeScript 项目将具备以下能力：

• ESLint 自动检测代码质量问题
• Prettier 自动格式化代码风格
• 两者规则协调一致，不会相互冲突
• VS Code 保存时自动修复
• Git 提交前自动检查，防止不合规范代码入库

整个团队只需遵守同一套规则，代码风格统一，Code Review 效率大幅提升。