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 中的定位、它对外暴露的核心 APIconfig()、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 为据可以梳理出以下对用户影响最大的节点版本日期核心变化7.0.02024-02-12引入 flat config 支持提升 ESLint、Node.js、TypeScript 最低版本要求8.0.02024-07-31大版本切换projectService稳定化、ban-types拆分、移除废弃规则8.42.02025-09-02弃用tseslint.config()推荐 ESLint 核心defineConfig()8.56.02026-02-16支持 ESLint v108.58.02026-03-30支持 TypeScript 68.65.02026-07-20检测到 TS 7 时输出警告8.67.02026-08-10导出基础globs2.1 v7.0.0flat 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.47.6.0 为共享配置与 flat config 类型增加name字段。这些条目共同勾勒出 v7 时期 flat config 从可用走向完整的过程。2.2 v8.0.0规则体系与项目服务的大规模重塑8.0.02024-07-31是本仓库中另一个里程碑。CHANGELOG 记录的 Feature 包括projectService稳定化EXPERIMENTAL_useProjectService正式更名并稳定为projectServiceban-types规则拆分被替换为no-restricted-types、no-unsafe-function-type、no-wrapper-object-typesno-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.0tseslint.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.1configs13 个共享配置index.ts通过createConfigsGettersindex.ts定义了 13 个共享配置均以惰性 getter 形式暴露并在首次访问时从调用栈推断候选的tsconfigRootDirall启用 typescript-eslint 提供的全部规则base仅设置运行所需的最小 parser/plugin 选项disableTypeChecked禁用类型感知检查与全部类型感知规则eslintRecommended禁用与 TypeScript 重复的eslint:recommended规则recommended/recommendedTypeChecked/recommendedTypeCheckedOnlystrict/strictTypeChecked/strictTypeCheckedOnlystylistic/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与extensionsv8.67.0 新增的基础设施8.67.0 的 export basic globs for using tseslint 落地为 src/globs.ts 中的两组导出extensionsjs [mjs,js,cjs,jsx]、ts [mts,ts,cts,tsx]、jsts为二者合并globsjs**/*.{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 严格校验字符串与嵌套extendsconfigImpl内置了三道校验分别对应 CHANGELOG 中的若干 Fixextends数组中出现字符串时直接报错明确提示这是defineConfig()的能力而非本函数的能力8.38.0 的字符串友好提示相关extends数组中出现带basePath的配置时报错8.36.0 引入basePath的同时禁止它在extends内出现extends数组中出现带extends的配置时报错即禁止嵌套 extends8.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://URL8.39.1 修复以及 Windows 上 jiti 产生的非规范化反斜杠路径8.42.0 修复。这样即使配置里没写tsconfigRootDir也能获得合理的类型感知默认值。五、版本支持矩阵ESLint / TypeScript / Node.jsCHANGELOG 中反复出现的 support TypeScript x.y 与 support ESLint vN 条目最终固化在 package.json 的声明中ESLint^8.57.0 || ^9.0.0 || ^10.0.0v8.56.0 正式支持 ESLint v10TypeScript4.8.4 6.1.08.26.0 支持 5.8、8.39.0 升级 5.9.2、8.58.0 支持 6.08.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 呈现的演进轨迹给出以下实操建议从tseslint.config()迁往defineConfig()自 8.42.0 起新项目应直接使用 ESLint 核心的defineConfig()搭配本包的configs、parser、plugin、globs组合配置存量配置可逐步迁移避免再新增对config()的依赖。注意 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。用globs简化文件匹配v8.67.0 起可直接使用tseslint.globs.ts/globs.tsDeclaration等现成 glob减少手写模式串的错误声明文件专项配置可参考 tests/globs.test.ts 中的匹配规则。关注版本对齐信号本包多数小版本为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考