typescript-eslint/parser 演进全解析从 CHANGELOG 看 TypeScript 解析器的能力变迁与关键配置【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint本文以packages/parser/CHANGELOG.md涵盖 v1.0.0 至 v8.70.0 的全部版本记录为骨架结合仓库内的 parser 源码、TypeScript ESTree 版本检测逻辑与官方文档系统梳理typescript-eslint/parser的功能演进脉络、关键parserOptions的来龙去脉以及同步发版机制、版本支持矩阵等实战信息。读完你将能根据版本号快速判断 parser 的能力边界并正确配置类型感知 lint 所需的关键选项。一、parser 在 typescript-eslint 生态中的定位typescript-eslint/parser是让 ESLint 能够解析 TypeScript 源码的桥接层。正如 Parser 官方文档 所解释的TypeScript 编译器产生的 AST 与 ESLint 要求的 ESTree 格式不兼容例如let x: number 1;中带类型注解的声明会让 ESLint 原生 Espree 直接报错同时 TypeScript 的 AST 为解析不完整代码 类型检查而优化而 ESTree 面向通用的 AST 遍历场景。从 packages/parser/src/index.ts 可以看到这个包的完整导出面parse与parseForESLintESLint 自定义 parser 的标准入口后者还附带scopeManager、services、visitorKeysclearCaches、createProgram、withoutProjectParserOptions、ParserServices等从typescript-eslint/typescript-estree转发出来的工具与类型version与meta对象meta含name: typescript-eslint/parser与当前版本号是在 5.55.0 版本 中新增导出的便于下游工具读取 parser 元信息。在 packages/parser/src/parser.ts 中核心入口parseForESLint完成了默认补全sourceType: script、解析onUnsupportedTypeScriptVersion的三种模式、强制开启comment/loc/range/tokens四个 AST 附属数据、调用parseAndGenerateServices生成 ESTree AST 与 parser services最后通过typescript-eslint/scope-manager的analyze完成作用域分析。二、从版本时间线看懂 parser 的能力演进CHANGELOG 中大量条目标注为 This was a version bump only for parser to align it with other projects这并非无意义重复——它揭示了本仓库采用monorepo 同步发版机制所有公开包parser、typescript-estree、eslint-plugin 等统一使用相同版本号发布正如 Versioning 文档 明确说明的所有包以相同版本号发布以协调发布与安装。因此 parser 的版本号本身就代表了整个工具链的进度。真正属于 parser 或与之强相关的功能变更集中在以下版本2.1 奠基期v1.0.0 - v5.x语法解析能力成型v1.0.0支持ecmaFeatures.jsx标志同时引入ecmaFeatures.jsx测试奠定 JSX 解析基础。v2.1.0options.project开始接受glob 模式#806为多 tsconfig 场景铺路。v3.0.0升级到 ESLint v7AST 对齐 ESTree 2020使用TSEmptyBodyFunctionExpression表示无函数体节点并新增allowInvalidAST选项。v4.32.0支持latest作为ecmaVersion取值。v5.15.0新增parserOptions.emitDecoratorMetadata让 parser 可以在不启用类型感知 lint 的情况下模拟tsconfig.json中emitDecoratorMetadata: true的行为。v5.45.1移除自动 JSX pragma 解析对jsx选项的强制依赖降低配置门槛。v5.55.0新增导出的meta对象前文已述。2.2 v6 时代类型服务与项目配置的探索v6.1.0在typescript-estree中引入实验性的EXPERIMENTAL_useProjectService选项#6754即用 TypeScript Project Service 生成类型信息的雏形——这正是后来projectService的起点。v6.21.0允许parserOptions.project: false为 override 配置中关闭类型感知提供了明确手段。v6.0.0大版本破坏性丢弃 ESLint v6、Node v12/v14/v17 支持typescript-estree新增allowInvalidAST、允许直接传入ts.SourceFile作为代码输入废弃createDefaultProgram并移除部分类型信息 programpartial type-information program。2.3 v7 时代flat config 与门槛升级v7.0.0⚠️ 破坏性提升 ESLint、Node.js 与 TypeScript 的最低版本要求并新增对flat config的支持。这也是parserOptions全面走入languageOptions.parserOptions时代的开始。v7.5.0parser 层面禁止用户配置errorOnTypeScriptSyntacticAndSemanticIssues——在 parser.ts 中可以看到该选项被强制硬编码为false目的是避免用户配置导致 ESLint 流程异常对应 issue#8681。v7.13.0导出withoutProjectParserOptions工具用于剥离触发类型信息解析的项目选项便于在插件中单文件隔离解析。2.4 v8 时代稳定化与前瞻兼容重点v8 是当前 CHANGELOG 覆盖最广、信息量最大的区间v8.0.0parser始终开启comment、loc、range、tokens见 parser.ts 中强制置true的代码因为这是 ESLint 工作的必备数据同时把EXPERIMENTAL_useProjectService正式稳定为projectService。v8.10.0 / v8.16.0 / v8.26.0依次支持 TypeScript 5.6 / 5.7 / 5.8。v8.18.0修复 TypeScript peer 依赖声明问题#10373。v8.22.0parser 新增standaloneisolatedDeclarations选项#10499允许在不启用project的情况下模拟 tsconfig 的isolatedDeclarations行为。v8.39.0更新至 TypeScript 5.9.2。v8.56.0支持ESLint v10。v8.58.0支持TypeScript 6同版本起getLib在 TS ≥ 6 时默认使用ScriptTarget.LatestStandard见 parser.ts。v8.58.2修复发布的包中残留tsbuildinfo缓存文件的问题#12187。v8.62.0移除冗余的package.jsonfiles字段#12444。v8.65.0两个重要变更详见下一节——新增onUnsupportedTypeScriptVersion选项以及检测到 TS 7 时输出警告。v8.70.0截至仓库的最新版纯版本对齐无代码变更。三、v8.65.0onUnsupportedTypeScriptVersion与 TS 7 预警在 v8.65.0 版本 中一次性出现了两条 feature值得重点展开。3.1onUnsupportedTypeScriptVersion三种模式该选项控制 parser 遇到未显式支持的 TypeScript 版本时的反应取值及其行为官方文档 Parser.mdx 中onUnsupportedTypeScriptVersion一节如下取值行为典型场景warn向控制台打印警告日志默认值日常开发error打印消息并抛出异常使本次 lint 失败CI 中拦截 Dependabot / Renovate 等自动升级引入的不受支持 TS 版本ignore静默不做任何事明确知晓版本差异、不想被打扰默认值为warn。在 parser.ts 中可以看到它同时处理了旧选项warnOnUnsupportedTypeScriptVersion的向后兼容若两者同时设置会直接抛错提示二选一若只设置了旧选项则true映射为warn、false映射为ignore。3.2 TS 7 检测与版本支持的硬边界同版本还加入了检测到 TS 7 时输出警告的能力。这与仓库中的版本支持策略互相印证packages/typescript-estree/src/version-check.ts 通过semver.satisfies对4.7 ~ 6.0逐一计算typescriptVersionIsAtLeast映射parser 的 peerDependencies 声明为typescript: 4.8.4 6.1.0、eslint: ^8.57.0 || ^9.0.0 || ^10.0.0见 packages/parser/package.json更硬的保护在 packages/parser/src/index.ts模块加载时会读取ts.versionMajorMinor若主版本 ≥ 7直接console.error提示typescript-eslint does not support TS 7.0并抛错退出避免在完全不兼容的 TS 7 API 下继续运行。这套警告非官方支持版本 硬失败明确不支持的 TS 7的分层策略是 parser 保持稳定性的重要设计。四、类型感知 lint 的两条配置路径project 与 projectServiceCHANGELOG 中projectv2.1.0 支持 glob、v6.21.0 支持false与projectServicev6.1.0 实验、v8.0.0 稳定的演进恰好勾勒出类型感知 lint 配置的两代方案project路径 / glob / 数组 /true/false/null。设置为true时每个源文件会向上查找最近的tsconfig.json同时可用projectFolderIgnoreList默认[**/node_modules/**]排除文件夹用tsconfigRootDir指定相对路径的解析根目录。注意使用 glob**会带来性能开销文档建议逐级使用单层*。projectService默认false启用后自动为每个文件使用最近的 tsconfig且可为未包含在 tsconfig 中的文件如eslint.config.js通过allowDefaultProject提供类型信息。子选项包括defaultProject默认tsconfig.json、loadTypeScriptPlugins默认false防止插件注册 watcher 导致 CLI 进程无法退出、maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING默认8等。两者同时开启会报错Enabling project does nothing when projectService is enabled.可用环境变量TYPESCRIPT_ESLINT_IGNORE_PROJECT_AND_PROJECT_SERVICE_ERRORtrue临时关闭该检查详见 Parser.mdx 的 Usage withprojectService一节。官方目前的推荐是优先使用projectService。五、装饰器与声明相关选项emitDecoratorMetadata / experimentalDecorators / isolatedDeclarations这三个选项的共同点是让 parser在未开启project的情况下模拟对应 tsconfig 编译选项的行为从而兼顾正确性与性能。它们在源码中的落地逻辑parser.ts非常直观services.emitDecoratorMetadata ?? parserOptions.emitDecoratorMetadata true; services.experimentalDecorators ?? parserOptions.experimentalDecorators true; services.isolatedDeclarations ?? parserOptions.isolatedDeclarations true;即把用户传入的 parser 选项写入services供规则与类型服务消费。三个选项默认值均为undefined等价不开启并在以下版本先后引入emitDecoratorMetadatav5.15.0#4646experimentalDecorators早在 scope 分析层就有配套支持v4.14.0 曾为装饰器元数据增加 scope 分析与consistent-type-imports支持isolatedDeclarationsv8.22.0#10499属于 parser 的 standalone 选项。六、从破坏性变更中提炼的升级注意点CHANGELOG 中标注的 Breaking Changes 是升级时最值得对照的清单v2.0.0设置project后默认对不在项目中的文件直接抛错#760recommended 配置变更视为破坏性。v4.0.0projectFolderIgnoreList从正则语义改为 glob 语义且不再接受RegExp。v6.0.0放弃 ESLint v6 与 Node v12/v14/v17。v7.0.0提升 ESLint、Node.js、TypeScript 最低版本要求开始支持 flat config。v8.0.0EXPERIMENTAL_useProjectService更名稳定为projectService旧名失效parser 强制开启comment/loc/range/tokens。七、结语packages/parser/CHANGELOG.md表面上是一份版本流水账实际却是 parser 能力边界的权威映射从 v1.0.0 的 JSX 支持到 v5 时代的装饰器选项到 v6/v7 的项目配置探索再到 v8 的projectService稳定化、onUnsupportedTypeScriptVersion分层告警与 TS 6 / ESLint v10 兼容。结合 parser.ts 的源码实现、version-check.ts 的版本矩阵与 Parser.mdx 的配置全解你可以按版本号回溯任何配置项的来源与用途也可以据 peer 依赖范围ESLint^8.57.0 || ^9.0.0 || ^10.0.0、TypeScript4.8.4 6.1.0规划自己的升级路径。【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
