TypeScript项目规范配置教程：ESLint与Prettier从零到生产环境

每次新开一个 TypeScript 项目，你是不是都要花半天时间重新配置 ESLint 和 Prettier？

网上找的教程要么版本过时，要么规则之间互相冲突，最后跑起来代码编辑器里全是红色波浪线，让人头疼。

其实，TypeScript、ESLint 和 Prettier 这三者完全可以和谐共存，配置起来并没有那么复杂。今天我们就来一步步搭建一套能直接用于生产环境的代码规范配置，帮你彻底告别繁琐的配置过程。

为什么需要这三件套？

首先，我们得搞清楚这三个工具各自的职责：

• TypeScript：负责静态类型检查，是保证代码健壮性的核心。
• ESLint：负责代码质量检查（比如未使用的变量、禁止的语法），也涵盖部分代码风格规则。
• Prettier：一个纯粹的代码格式化工具，专一于统一缩进、引号、分号等代码风格。

简单来说，它们分工明确：ESLint 管质量，Prettier 管美观，TypeScript 管类型。

但问题也随之而来：ESLint 的部分代码风格规则可能会和 Prettier 的格式化结果产生冲突，同时 ESLint 需要特殊配置才能正确解析 TypeScript 语法。下面，我们就来解决这些问题。

基础配置步骤

1. 安装依赖

在项目根目录下，运行以下命令安装必要的 npm 包：

npm install -D eslint prettier typescript
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm install -D eslint-config-prettier eslint-plugin-prettier

简单解释一下这些包的作用：

• @typescript-eslint/parser：让 ESLint 能够理解 TypeScript 语法。
• @typescript-eslint/eslint-plugin：提供一系列专为 TypeScript 设计的 ESLint 规则。
• eslint-config-prettier：关闭 ESLint 中所有与 Prettier 冲突的规则，这是两者和平共处的关键。
• eslint-plugin-prettier：将 Prettier 作为一条 ESLint 规则来运行（可选，我个人更倾向于将两者分开执行）。

2. 创建 Prettier 配置文件（.prettierrc）

在项目根目录创建 .prettierrc 文件，定义你的代码风格。这里是一个常用配置示例：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "endOfLine": "auto"
}

你可以根据团队习惯进行调整，关键是整个项目要保持统一。

3. 创建 ESLint 配置文件（.eslintrc.js）

在项目根目录创建 .eslintrc.js 文件，这是 ESLint 的核心配置。

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier', // 一定要放在最后，用于覆盖前面的冲突规则
  ],
  plugins: ['@typescript-eslint'],
  env: {
    node: true,
    es6: true,
  },
  rules: {
    // 这里可以覆盖或添加自定义规则
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
  },
};

如果你的项目是前端项目（运行在浏览器环境），还需要在 env 字段中添加 browser: true。

解决 ESLint 和 Prettier 的冲突

上面的配置中，extends: ['prettier'] 就是解决冲突的关键。它引用了 eslint-config-prettier 这个包，作用是将所有与 Prettier 格式化结果冲突的 ESLint 规则全部关闭。

重要：prettier 这个配置项必须放在 extends 数组的最后，这样才能确保它能成功覆盖前面所有扩展配置中的冲突规则。

如果你想在运行 eslint --fix 时自动执行 Prettier 格式化，可以添加 plugin:prettier/recommended 配置。但我更推荐将两者分开运行：

• eslint 只专注于检查代码质量问题。
• prettier --write 只负责格式化代码风格。

这样职责更清晰，也便于排查问题。

集成 TypeScript 的完整规则集

如果你希望对类型有更严格的检查，可以将配置中的 plugin:@typescript-eslint/recommended 替换为 plugin:@typescript-eslint/recommended-requiring-type-checking。但请注意，后者需要额外的解析器配置：

parserOptions: {
  project: './tsconfig.json',
  tsconfigRootDir: __dirname,
},

这会启用一些基于类型信息的强大规则（例如 @typescript-eslint/no-floating-promises，用于检查未处理的 Promise），但代价是会显著降低代码检查的速度。请根据项目实际情况按需开启。

可直接复用的配置模板

适用于 Node.js 项目

// .eslintrc.js
module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier',
  ],
  plugins: ['@typescript-eslint'],
  env: {
    node: true,
    es2021: true,
  },
  rules: {
    '@typescript-eslint/no-explicit-any': 'warn',
    '@typescript-eslint/explicit-module-boundary-types': 'off',
  },
};

适用于 React + TypeScript 项目

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier',
  ],
  plugins: ['react', '@typescript-eslint'],
  env: {
    browser: true,
    es2021: true,
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
  rules: {
    'react/react-in-jsx-scope': 'off', // 新版本 React (17+) 不需要手动引入 React
  },
};

使用此配置前，别忘了安装对应的插件：npm install -D eslint-plugin-react eslint-plugin-react-hooks。

集成到编辑器与构建流程

VSCode 自动修复

在项目根目录创建 .vscode/settings.json 文件，实现保存时自动修复和格式化：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

这样，每次保存文件时，VSCode 会自动调用 ESLint 修复问题，并用 Prettier 格式化代码。

package.json 脚本

在 package.json 的 scripts 字段中添加以下命令，方便在命令行和 CI/CD 流程中使用：

{
  "scripts": {
    "lint": "eslint src --ext .ts,.tsx",
    "lint:fix": "eslint src --ext .ts,.tsx --fix",
    "format": "prettier --write \"src/**/*.{ts,tsx,json,css}\""
  }
}

在持续集成（CI）流水线中，可以运行 npm run lint 来检查代码规范，运行 npx prettier --check \"src/**/*.{ts,tsx}\" 来检查代码格式是否统一。

常见问题

1. ESLint 报错 “Parsing error: Cannot find module ‘typescript’”

请确保 typescript 包已经安装在 devDependencies 中，并且其版本与 @typescript-eslint/parser 兼容。

2. 规则冲突怎么调试？

运行 npx eslint --print-config your-file.ts 命令，可以查看最终应用到该文件的所有 ESLint 规则及其来源，确认 prettier 配置是否成功覆盖了冲突规则。

3. 要不要用 eslint-plugin-prettier？

这取决于个人或团队的偏好。它的好处是只需运行 eslint --fix 就能一次性完成代码质量修复和格式化。缺点是可能会稍微降低检查速度，且在某些边缘情况下规则覆盖可能不彻底。我个人倾向于将两者分开，逻辑更清晰。

4. 如何与 Webpack/Vite 等构建工具集成？

在 Webpack 中，可以使用 eslint-loader 或 eslint-webpack-plugin 在开发时提供实时提示。在 Vite 中，其官方 React 或 Vue 插件通常已内置了对 ESLint 的支持，具体配置请查阅对应插件的文档。

总结

为 TypeScript 项目配置一套完整的代码规范工具链并不复杂，核心在于理解每个工具的分工并正确解决它们之间的冲突。通过 @typescript-eslint 系列插件让 ESLint 理解 TypeScript，再通过 eslint-config-prettier 化解 ESLint 与 Prettier 的规则冲突。

你可以将本文的配置保存为模板，下次启动新项目时直接复制使用，能节省大量重复配置的时间。记住，良好的代码规范不是对开发者的束缚，而是团队高效协作、项目长期维护的基石。让机器去处理格式问题，开发者才能更专注于业务逻辑的实现。

最后，这里有一个快速检查清单，帮你确认配置是否完成：

• 已安装 eslint, prettier, typescript 及相关插件。
• 已正确配置 .eslintrc.js 和 .prettierrc 文件。
• .eslintrc.js 的 extends 数组中包含了 'prettier'，并且它位于数组末尾。
• 编辑器已配置为保存时自动执行修复和格式化。
• package.json 中已添加相应的 npm 脚本，用于本地检查和 CI 流程。