typescript-eslint 的 recommended、strict 与 stylistic 共享配置怎么选？

typescript-eslint 的 recommended、strict 与 stylistic 共享配置怎么选？

【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint

在 TypeScript 项目里用 typescript-eslint 工具链做 ESLint 检查时，eslint.config.mjs的第一个决策就是把哪个共享配置写进extends：tseslint.configs.recommended、tseslint.configs.strict，还是tseslint.configs.stylistic。这三者不是"三选一"的互斥关系，各自承担不同职责，且有各自的稳定性保证。本文基于官方文档给出选择依据、对应的 flat config 写法，以及如何运行验证配置生效。

适用前提：使用 ESLint 的 flat config 格式（eslint.config.mjs），通过主入口包typescript-eslint消费共享配置。

准备条件：安装与基础配置

在项目中安装 ESLint、TypeScript 与 typescript-eslint 工具链：

npm install --save-dev eslint @eslint/js typescript typescript-eslint

然后在项目根目录创建eslint.config.mjs，先写入最基础的recommended配置：

// @ts-check import js from '@eslint/js'; import { defineConfig } from 'eslint/config'; import tseslint from 'typescript-eslint'; export default defineConfig({ files: ['**/*.{js,ts}'], extends: [js.configs.recommended, tseslint.configs.recommended], });

几个配置项的说明（以 Quickstart 文档为准）：

• // @ts-check让 TypeScript 类型检查配置文件本身，便于编辑器提示与写配置时抓错；如果与你的 TS 环境冲突，可以删掉。
• defineConfig(...)是当前版本 ESLint 内置的可选辅助函数。
• files/extends组合会把extends中的配置限制在 JS/TS 文件上，官方建议这样写以避免对 CSS、Markdown 等其他文件类型启用 ESLint 时出问题，但完全可选。如需覆盖所有标准 JS/TS 扩展名，可改用files: ['**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}']。
• 文件名用.mjs是为了让 Node 按 ESM 处理该文件；如果package.json中有"type": "module"，也可以用eslint.config.js。

三个配置各自负责什么

官方文档（Shared Configurations）对这三个配置的定位如下：

• recommended：面向代码正确性的规则，可以"drop in"直接使用、无需额外配置。这些规则的告警几乎都是坏实践或大概率是 bug。它同时会禁用那些与 typescript-eslint 规则冲突、或在 TypeScript 代码库中会出问题的核心 ESLint 规则。
• strict：包含全部recommended，再加上一批同样能抓 bug、但更"opinionated"（主观倾向更强）的规则，这些规则不一定适合所有项目。另外，一些在recommended中已启用的规则，在strict里默认采用更严格的设置。
• stylistic：现代 TypeScript 代码库的最佳实践规则，但不影响程序逻辑，普遍倾向强制更简洁的代码模式。注意stylistic不替代recommended或strict，它在正确性配置之上追加规则，所以要和其中一个正确性配置一起用，而不是二选一。

具体的规则清单可以直接在仓库源码中核对，例如 strict 配置、recommended 配置、stylistic 配置。

按团队情况选择：是否升级到 strict

选择recommended还是strict，文档给出的判断标准是团队构成，而不是技术偏好：

If a majority of developers working on your project are comfortable with TypeScript and typescript-eslint, consider replacingrecommendedwithstrict.

即：当项目中大多数开发者熟悉 TypeScript 和 typescript-eslint 时，才考虑用strict替换recommended。官方在strict章节还有同样的提示：只有当"非微不足道比例"（a nontrivial percentage）的开发者高度熟悉 TypeScript 时，才建议扩展strict。

对于没有开启类型感知 linting 的项目，官方建议的起步组合是recommended+stylistic：

export default defineConfig({ files: ['**/*.{js,ts}'], extends: [ js.configs.recommended, tseslint.configs.recommended, tseslint.configs.stylistic, ], });

团队符合条件时，把tseslint.configs.recommended一行换成tseslint.configs.strict即可（stylistic保留）：

export default defineConfig({ files: ['**/*.{js,ts}'], extends: [ js.configs.recommended, tseslint.configs.strict, tseslint.configs.stylistic, ], });

可选分支：项目开启了类型检查

如果项目开启了 typed linting，官方建议的起步组合换成带类型信息的版本：recommended-type-checked+stylistic-type-checked；团队熟悉度符合上面的条件时，再把前者换成strict-type-checked：

export default defineConfig( { files: ['**/*.{js,ts}'], extends: [ js.configs.recommended, tseslint.configs.recommendedTypeChecked, tseslint.configs.stylisticTypeChecked, ], }, // 其余配置（如 languageOptions.parserOptions）... );

使用 type-checked 配置还必须按 Typed Linting 文档 配置languageOptions.parserOptions，否则类型感知规则无法工作。

运行与验证

在项目根目录运行：

npx eslint .

（使用 Yarn 或 pnpm 的项目对应yarn eslint ./pnpm eslint .。）ESLint 会检查当前目录下所有 TypeScript 兼容文件，并把结果输出到终端。

验证配置是否生效可以从两个角度判断：

1. 命令能正常跑完并输出检查报告，说明extends中的共享配置加载成功。
2. 切换配置前后告警集合的变化符合各配置的定位：从recommended升到strict后，会多出strict特有规则的报错（如 strict 源码 中列出的@typescript-eslint/no-non-null-assertion、@typescript-eslint/no-unsafe-function-type、@typescript-eslint/triple-slash-reference等）；加上stylistic后，则多出风格类规则的报错，但不影响逻辑检查。

官方明确说明这些共享配置是"推荐起点"，但不要求原样使用：ESLint 允许在扩展共享配置的基础上单独配置规则（在自己的配置块里写rules覆盖即可），觉得某条规则不适合项目时可以逐条调整，而不必在配置之间来回取舍。

稳定性与边界

选择时还要注意各配置的稳定性差异（以 Shared Configurations 文档 为准）：

• 除all、strict和strict-type-checked之外，其余配置都视为"stable"：规则的增删属于 breaking change，只会在主版本升级时发生。
• strict与strict-type-checked不受 semver 稳定性约束：其启用的规则和/或选项可能在非主版本更新中变化。升级 minor 版本后如果strict的报错集合发生变化，这是文档声明过的行为，不是配置被破坏。
• typescript-eslint 的任何预设配置都不启用格式化规则（只约束空白与格式碎片的规则）。官方强烈建议用 Prettier 或同类工具做格式化，而不是 ESLint 格式化规则，参见 What About Formatting?。

官方同样不推荐直接扩展all（规则互相冲突、很多规则需要按项目配置），base也仅用于内部基础、不推荐直接使用——正常项目的正确性配置仍应落在recommended/strict（及对应 type-checked 版本）上。

下一步

• 需要启用类型感知 linting 时，按 Typed Linting 配置languageOptions.parserOptions，再把组合升级为 type-checked 版本。
• 需要单独调整某条规则时，查看 规则文档入口 中指向的规则列表，或在 Shared Configurations 文档 中按配置名定位对应章节。
• 仍跑不通时，参考 Quickstart 指向的 Troubleshooting & FAQs。

【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint