企业官网建设流程全解析

typescript-eslint 一体化包版本演进与核心 API 解读：从 v7 到 v8 的 CHANGELOG 深析

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

本文以仓库中 packages/typescript-eslint/CHANGELOG.md 为骨架，系统梳理typescript-eslint一体化包从 v6.21 到 v8.70 的版本演进、破坏性变更与 API 沉淀。读者可据此理解该聚合包在 monorepo 中的定位、它对外暴露的核心 API（config()、configs、parser、plugin、globs、Compatible*类型），以及升级大版本时需要关注的关键信号，并掌握如何在 flat config 与defineConfig()时代正确接入 TypeScript ESLint。

一、包的定位：为什么这个 CHANGELOG 里有大量 "version bump only" 条目

通读 CHANGELOG.md 可以发现一个显著特征：在 8.x 中后期，大量版本（如 8.55.0、8.57.0、8.60.0、8.66.0 等）都只写着同一句话：

This was a version bump only for typescript-eslint to align it with other projects, there were no code changes.

这是理解该包性质的关键线索。typescript-eslint是一个面向最终用户的一体化聚合包，它不直接实现规则或解析逻辑，而是将 monorepo 内各核心包重新组装后一次性导出。从 package.json 的dependencies可以看到它的真实构成：

• @typescript-eslint/eslint-plugin（规则插件）
• @typescript-eslint/parser（解析器）
• @typescript-eslint/typescript-estree（底层 AST 转换）
• @typescript-eslint/utils（工具与类型）

因此，当上游包发布新版本时，本包即使没有任何代码改动，也需要同步发版以保持版本号对齐——这正是 CHANGELOG 中大量 "version bump only" 条目的来源。8.62.0 中 "remove redundant package.json files"、8.58.2 中 "remove tsbuildinfo cache file from published packages" 这类条目，也印证了该包的发布内容主要是面向消费端的聚合与打包配置。

二、版本演进时间线：关键节点一览

以 CHANGELOG.md 为据，可以梳理出以下对用户影响最大的节点：

2.1 v7.0.0：flat config 时代的开端

7.0.0 是 CHANGELOG 中明示带 "Breaking Changes" 标记的版本，两条 Feature 分别是：

• 提升 ESLint、Node.js、TypeScript 的最低版本要求；
• 新增对 flat config 的支持。

从此，用户可以写出tseslint.config(...)形式的配置文件。值得注意的是，v7 时期该包同时开始补齐 flat config 生态的配套设施，例如：

• 7.1.0 新增*-type-checked-only系列配置（CHANGELOG 7.1.0 条目）；
• 7.2.0 导出ConfigWithExtends类型，并在 base 共享配置中设置sourceType: "module"，同时支持 TypeScript 5.4；
• 7.6.0 为共享配置与 flat config 类型增加name字段。

这些条目共同勾勒出 v7 时期 flat config 从"可用"走向"完整"的过程。

2.2 v8.0.0：规则体系与项目服务的大规模重塑

8.0.0（2024-07-31）是本仓库中另一个里程碑。CHANGELOG 记录的 Feature 包括：

• projectService稳定化：EXPERIMENTAL_useProjectService正式更名并稳定为projectService；
• ban-types规则拆分：被替换为no-restricted-types、no-unsafe-function-type、no-wrapper-object-types；
• no-empty-object-type从ban-types与no-empty-interfaces中拆分独立；
• 移除废弃规则（no-throw-literal、no-useless-template-literals等）；
• no-unnecessary-type-parameters提升为 strict 级别。

同时 Fixes 中有一条值得注意：在disabled-type-checked共享配置中禁用projectService——这说明该配置的作用是彻底关停类型感知能力，无论底层走哪种项目服务方式。

2.3 v8.42.0：tseslint.config()的正式弃用

8.42.0 是一个对配置写法影响深远的节点：官方开始弃用tseslint.config()，理由是 ESLint 核心现已通过defineConfig()提供同样的能力。这一决策的源码证据可以在 config-helper.ts 的 JSDoc 中看到：

@deprecatedESLint core now provides this functionality viadefineConfig(), which we now recommend instead.

与此同时，8.38.0 中tseslint.config()对嵌套extends直接报错、8.36.0 为其新增basePath支持，说明在弃用之前，官方仍在补齐该辅助函数的健壮性。用户的迁移路径是：保留typescript-eslint包导出的configs、parser、plugin、globs，改用eslint/config的defineConfig()组装。

三、核心导出 API：以源码验证 CHANGELOG 沉淀的能力

CHANGELOG 中 8.46.0（导出 util 类型）、8.59.4（导出Compatible*类型解决 pnpm TS 报错）、8.67.0（导出 globs）等条目，都指向同一个事实：该包的导出面在持续扩张。结合 src/index.ts 可确认其最终导出清单。

3.1configs：13 个共享配置

index.ts通过createConfigsGetters（index.ts）定义了 13 个共享配置，均以惰性 getter 形式暴露，并在首次访问时从调用栈推断候选的tsconfigRootDir：

• all：启用 typescript-eslint 提供的全部规则；
• base：仅设置运行所需的最小 parser/plugin 选项；
• disableTypeChecked：禁用类型感知检查与全部类型感知规则；
• eslintRecommended：禁用与 TypeScript 重复的eslint:recommended规则；
• recommended/recommendedTypeChecked/recommendedTypeCheckedOnly；
• strict/strictTypeChecked/strictTypeCheckedOnly；
• stylistic/stylisticTypeChecked/stylisticTypeCheckedOnly。

这些配置的实体位于 packages/eslint-plugin/src/raw-plugin.ts 的flatConfigs映射中，即flat/base、flat/recommended、flat/strict-type-checked等 13 个 flat 配置项。

3.2parser与plugin：保证身份一致性的设计

index.ts中parser与plugin的导出（index.ts）并非简单地再导出，而是刻意保持与@typescript-eslint/eslint-plugin的对象身份一致：直接复用pluginBase，避免出现require('typescript-eslint').plugin !== require('@typescript-eslint/eslint-plugin')的分叉（源码注释对此有专门说明）。这样第三方共享配置无论引用哪个包，都不会因插件对象不一致而破坏用户的配置解析。

3.3globs与extensions：v8.67.0 新增的基础设施

8.67.0 的 "export basic globs for using tseslint" 落地为 src/globs.ts 中的两组导出：

• extensions：js = ['mjs','js','cjs','jsx']、ts = ['mts','ts','cts','tsx']、jsts为二者合并；
• globs：js=**/*.{mjs,js,cjs,jsx}、ts=**/*.{mts,ts,cts,tsx}、jsts为合并 glob，另有匹配声明文件的tsDeclaration=**/*.{d.ts,d.*.ts}。

tsDeclaration的行为有专门测试覆盖（tests/globs.test.ts）：它能匹配file.d.ts与file.d.css.ts这类带附加扩展名的声明文件，但不会误匹配file.dts或file.ts。在defineConfig()时代，可以用它写出针对声明文件的专项配置：

import { defineConfig } from 'eslint/config'; import tseslint from 'typescript-eslint'; export default defineConfig( { name: 'config-for-TypeScript', files: [tseslint.globs.ts], extends: [tseslint.configs.recommended], }, { name: 'disable-rules-for-declaration-files', files: [tseslint.globs.tsDeclaration], rules: { 'no-var': 'off', }, }, );

3.4Compatible*类型：双配置体系的兼容层

8.59.4 修复的 pnpm TS 报错，根源在于typescript-eslint的配置文件常在@ts-check且未纳入 tsconfig 的场景下被消费。为此该包导出 compatibility-types.ts 中定义的CompatibleParser、CompatibleConfig、CompatibleConfigArray、CompatiblePlugin四类刻意放宽的类型，使同一份导出既满足defineConfig()的严格类型，又兼容tseslint.config()的旧签名。这与 8.40.0 中 "exportplugin,parser, andconfigsthat are compatible with both" 的目标一脉相承。

四、config()辅助函数的演进与内部行为

虽然tseslint.config()已在 8.42.0 弃用，但其演进历史本身是理解 flat config 语义的绝佳教材，也解释了 8.31.0、8.38.0 等条目反复修复其行为的动机。

4.1extends的扁平化语义

config()的核心是 config-helper.ts 中的configImpl：所有参数先flat(Infinity)扁平化，再对带extends的对象做展开——extends数组中的每个配置对象都会被注入外层配置的files、ignores、basePath与合并后的name，然后与剩余配置一起平铺为 ESLint 认识的配置数组。8.15.0 的 "allow infinitely deep array nesting in config function and extends" 即对应InfiniteDepthConfigWithExtends类型（config-helper.ts）。

4.2 严格校验：字符串与嵌套extends

configImpl内置了三道校验，分别对应 CHANGELOG 中的若干 Fix：

• extends数组中出现字符串时直接报错，明确提示这是defineConfig()的能力而非本函数的能力（8.38.0 的字符串友好提示相关）；
• extends数组中出现带basePath的配置时报错（8.36.0 引入basePath的同时禁止它在extends内出现）；
• extends数组中出现带extends的配置时报错，即禁止嵌套 extends（8.38.0 "error on nested extends"）。

4.3 全局 ignores 的特判

isPossiblyGlobalIgnores 判定：若一个配置对象只包含name、ignores、basePath键，则视为全局 ignores 对象——它会原样透传而不注入files，且不会被当作父配置混入其他扩展（8.31.0 中 "address bugs in config() around global ignores" 正是修复此处）。7.1.1 的 "applyignoresto all extended configs" 则保证了父级的ignores能正确下沉到所有扩展配置。

4.4tsconfigRootDir的自动推断

8.37.0 / 8.38.0 / 8.39.1 连续三个版本在完善一个能力：从调用栈推断tsconfigRootDir。getTSConfigRootDirFromStack.ts 通过 V8 Stack Trace API 捕获调用栈，找到名为eslint.config.{c,m}{j,t}s的配置文件所在目录作为候选根目录；同时兼容 ESM 的file://URL（8.39.1 修复）以及 Windows 上 jiti 产生的非规范化反斜杠路径（8.42.0 修复）。这样即使配置里没写tsconfigRootDir，也能获得合理的类型感知默认值。

五、版本支持矩阵：ESLint / TypeScript / Node.js

CHANGELOG 中反复出现的 "support TypeScript x.y" 与 "support ESLint vN" 条目，最终固化在 package.json 的声明中：

• ESLint：^8.57.0 || ^9.0.0 || ^10.0.0（v8.56.0 正式支持 ESLint v10）；
• TypeScript：>=4.8.4 <6.1.0（8.26.0 支持 5.8、8.39.0 升级 5.9.2、8.58.0 支持 6.0；8.65.0 起若检测到 TS 7 会在 index.ts 中打印警告并抛错，提示使用 TS 6 API 侧载运行）；
• Node.js：^18.18.0 || ^20.9.0 || >=21.1.0。

此外 8.18.0 的 "typescript peer dependency" 与 7.4.0 的 "declare peer dependency onutils" 均属于依赖声明修复，目的是让 pnpm 等严格安装器能正确解析依赖树——这一点与 8.59.4 修复的问题同源，都是在用户侧安装场景下保证类型与运行时一致性。

六、升级与迁移建议

基于 CHANGELOG 呈现的演进轨迹，给出以下实操建议：

1. 从tseslint.config()迁往defineConfig()：自 8.42.0 起新项目应直接使用 ESLint 核心的defineConfig()，搭配本包的configs、parser、plugin、globs组合配置；存量配置可逐步迁移，避免再新增对config()的依赖。
2. 注意 v8 的规则体系变化：若从 v7 升级，需处理ban-types→no-restricted-types/no-unsafe-function-type/no-wrapper-object-types、no-throw-literal→only-throw-error、no-useless-template-literals移除等规则改名与删除（均记录于 8.0.0 与 7.x 条目），并关注projectService已稳定取代EXPERIMENTAL_useProjectService。
3. 用globs简化文件匹配：v8.67.0 起可直接使用tseslint.globs.ts/globs.tsDeclaration等现成 glob，减少手写模式串的错误，声明文件专项配置可参考 tests/globs.test.ts 中的匹配规则。
4. 关注版本对齐信号：本包多数小版本为 "version bump only"，当某版本 CHANGELOG 中出现 Feature/Fix 时，往往意味着上游 parser、plugin 或 estree 有实质变化，升级后建议跑一遍全量 lint 与测试验证。

七、结语

从 packages/typescript-eslint/CHANGELOG.md 可以看到，typescript-eslint作为聚合包的价值不在"实现"，而在"组装"：它把 parser、plugin、estree、utils 的能力收敛为一套简洁、类型安全、且持续向 ESLint 官方 API 靠拢的消费入口。理解它的版本语义与导出面（index.ts、config-helper.ts、globs.ts），就能在升级与配置时准确判断哪些变化影响自己、哪些可以放心跟随。

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