构建工具前端【免费下载链接】esbuildAn extremely fast bundler for the web项目地址https://gitcode.com/GitHub_Trending/es/esbuild点击查看免费下载esbuild 项目维护着一套完整的 JavaScript API 类型定义lib/shared/types.ts供esbuild、esbuild-wasm等 npm 包的 TypeScript 用户消费。为了让这些类型定义在较老的 TypeScript 编译器中依然可用仓库专门设置了require/old-ts目录并配套了test-old-ts测试目标。本文以require/old-ts/README.md为线索结合 Makefile、lib/shared/types.ts 与相关配置完整剖析这套旧版 TypeScript 回归测试的动机、实现与运行方式读者可据此复现验证也能把同样的思路迁移到自己的开源库中。一、背景esbuild 的类型定义从何而来esbuild 的 JavaScript APIbuild、transform、serve、context等类型声明并不是手写在每个 npm 包里的而是统一维护在 lib/shared/types.ts 一个源文件中。正如 lib/README.md 所述This directory contains the TypeScript code that becomes the JavaScript API code in theesbuildandesbuild-wasmpackages. Its automatically built during the build process for those packages.也就是说类型定义源文件会在make platform-neutral、make platform-wasm等构建流程中被打包进发布产物。lib/shared/types.ts全文约 720 行定义了BuildOptions、TransformOptions、ServeOptions、Message、Location、Metafile等完整 API 类型例如lib/shared/types.ts#L10-L95 的CommonOptions汇总了sourcemap、format、target、minify、jsx、define、logLevel等通用配置lib/shared/types.ts#L116-L177 的BuildOptions补充了bundle、splitting、outfile、outdir、external、loader、plugins等打包专属选项lib/shared/types.ts#L226-L235 的BuildResult使用了ProvidedOptions[write] extends false ? never : undefined这类条件类型根据传入的write选项精确推导返回结构中outputFiles字段的存在性。正是因为类型定义面向的是所有TypeScript 用户它就必须在尽量老的编译器版本上也能通过语法与类型检查否则下游用户可能因为SyntaxError或类型错误而无法使用 esbuild 的 API。二、问题类型定义容易悄悄用上新语法类型定义文件由项目维护者编写日常开发与自测通常使用最新版 TypeScript。这带来一个隐蔽风险维护者可能无意中使用了旧版 TypeScript 尚不支持的语法或类型特性如较新的关键字、较新的条件类型写法、新版内置工具类型等。在最新编译器下一切正常但老用户一升级 esbuild 包就会遇到编译失败体验很差。require/old-ts/README.md只有一句话却精准概括了这套目录的用途This is used to ensure that our type definitions dont accidentally use newer features that break in older versions of TypeScript.即用一套固定老版本的 TypeScript 去编译类型定义作为回归测试防止新特性悄悄溜进.d.ts。三、方案require/old-ts 目录的组成require/old-ts是一个极简的独立 Node 工程仅用于固定旧版 TypeScript 工具链{ dependencies: { typescript: 3.5.3 } }对应的 require/old-ts/package-lock.json 中锁定了typescript3.5.3并声明其node 4.2.0的引擎要求。选型 3.5.3 的意图很明确它是 2019 年发布的一个被广泛使用的稳定版本把它作为兼容性下限来把关类型定义能覆盖绝大多数的存量用户环境。仓库中还有一个细节佐证了这种以老版本为护栏的取向主类型检查用的 lib/package.json 依赖typescript6.0.2与require/old-ts形成了新版本做主检、老版本做回归的双层防护。四、核心实现Makefile 中的 test-old-ts 目标整套测试逻辑集中在一个 Makefile 目标里见 Makefile#L142-L149require/old-ts/node_modules: cd require/old-ts npm ci test-old-ts: | require/old-ts/node_modules rm -fr scripts/.test-old-ts mkdir scripts/.test-old-ts cp lib/shared/types.ts scripts/.test-old-ts/main.d.ts cd scripts/.test-old-ts ../../require/old-ts/node_modules/.bin/tsc *.d.ts rm -fr scripts/.test-old-ts逐步拆解它的执行流程准备依赖test-old-ts声明前置目标require/old-ts/node_modules首次运行时执行cd require/old-ts npm ci按 lockfile 精确安装typescript3.5.3npm ci而非npm install保证每次测试的环境完全一致。复制类型定义把lib/shared/types.ts复制为临时目录scripts/.test-old-ts/main.d.ts。复制成.d.ts后缀并改名为main是为了让旧版tsc把它当作一个独立的声明文件参与编译。用旧编译器编译在scripts/.test-old-ts内调用../../require/old-ts/node_modules/.bin/tsc *.d.ts用 TypeScript 3.5.3 的tsc直接编译这份声明文件。只要其中出现任何 3.5.3 无法解析的语法或类型构造tsc就会报错测试随即失败。清理现场无论成败最后rm -fr scripts/.test-old-ts删除临时目录保证不污染工作区、不产生构建残留。这条链路的关键点在于test-old-ts验证的是语法与类型层面的可编译性而不是语义等价性——它不关心 esbuild 运行时行为只保证.d.ts在旧编译器下能被干净地解析。五、为什么选 TypeScript 3.5兼容基线的权衡选择 3.5.3 作为最老被测版本并非随意而是对维护成本与覆盖范围的平衡太老如 2.x会引入过多历史兼容负担且与 esbuild 类型定义实际用到的语法如条件类型、Record工具类型等完全不匹配测试将失去区分度太新如 4.x、5.x则无法拦住真正的老用户痛点护栏形同虚设。3.5.3 恰好位于支持大部分现代类型语法与能暴露较新语法特性的交界处。同时由于依赖被npm ci锁定无论何时运行make test-old-ts拿到的都是同一份编译器二进制结果可稳定复现。从lib/shared/types.ts的实际内容看类型定义大量使用了Recordstring, ...、条件类型extends ... ? ... : ...、可选链外的联合类型推导等构造这些在 3.5 中均可解析恰好验证了该基线选择的合理性。六、与仓库其他类型检查机制的配合test-old-ts并非孤立的类型保障它与仓库中的其他检查共同构成三层防线机制工具链覆盖范围位置test-old-tsTypeScript 3.5.3类型定义文件.d.ts的向后兼容性Makefile#L145-L149lib-typecheck-node最新版 TypeScript6.0.2lib目录全部 TypeScript 源码的类型自检Makefile#L156-L157、lib/tsconfig.jsonts-type-tests仓库内 node_modules通过scripts/ts-type-tests.js对构建出的esbuild包做类型行为断言scripts/ts-type-tests.js三者分工明确lib-typecheck-node保证新编译器下类型定义自身正确ts-type-tests例如 scripts/ts-type-tests.js#L13-L19 中esbuild.buildSync({})、esbuild.build({})的用例验证类型行为与运行时结果一致而test-old-ts专门保证老编译器下不炸。lib/tsconfig.json中module: CommonJS、target: es2017、strict: true等选项也说明主类型检查使用的是严格的现代配置与老版本回归测试形成互补。七、如何本地复现验证在当前仓库根目录下即可执行# 仅运行旧版 TypeScript 兼容性测试 make test-old-ts # 运行完整的 lib 类型检查含新版本自检 make lib-typecheck流程为先触发npm ci安装 3.5.3再复制类型定义、用旧版tsc编译、最后清理临时目录。若lib/shared/types.ts后续引入了 3.5.3 不支持的语法例如更新的内置类型或语法糖make test-old-ts会立刻以tsc报错的形式拦截从而在发布前发现兼容性回归。开发者在修改lib/shared/types.ts时也可以先跑一遍make test-old-ts作为快速反馈。八、总结require/old-ts用不到十行 Makefile 规则就为 esbuild 的类型定义建立了一条最老版本护栏以锁定的 TypeScript 3.5.3 编译.d.ts用最小成本拦截向后兼容性回归。这套模式对任何面向广泛 TypeScript 用户群的开源库都具有直接借鉴价值——维护一份老编译器编译测试比依赖维护者自律更可靠。对 esbuild 而言它保障了lib/shared/types.ts这份 720 行的 API 声明在各类用户环境中都能被稳定解析是极速打包器在类型体验层面同样可靠的底气来源。赞分享构建工具前端【免费下载链接】esbuildAn extremely fast bundler for the web项目地址https://gitcode.com/GitHub_Trending/es/esbuild点击查看免费下载相关推荐OpenChamber 1.10.1 发布详解一键 Git 同步与 Stash 管理实战指南OpenChamber 1.10.1 发布详解一键 Git 同步与 Stash 管理实战指南 OpenChamber 1.10.12026 05 06 发布AI Agent人工智能代码智能体交互助手Blockly TypeScript 类型测试以编译即通过保障 API 类型定义的向后兼容Blockly TypeScript 类型测试以编译即通过保障 API 类型定义的向后兼容 TypeScript 测试 packages/blockly/t前端低代码UI组件Skel常见问题解答开发者必知的10个解决方案Skel常见问题解答开发者必知的10个解决方案 Skel作为一款轻量级响应式框架在开发过程中难免会遇到各种问题。本文整理了开发者最常遇到的10个问题及解决方前端上一篇CANN动态MX量化算子API下一篇10分钟上手Douyin-Bot人脸识别黑科技从截图到高颜值检测全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 esbuild 旧版 TypeScript 兼容性测试机制：用 TypeScript 3.5 守护 JS API 类型定义
构建工具前端【免费下载链接】esbuildAn extremely fast bundler for the web项目地址https://gitcode.com/GitHub_Trending/es/esbuild点击查看免费下载esbuild 项目维护着一套完整的 JavaScript API 类型定义lib/shared/types.ts供esbuild、esbuild-wasm等 npm 包的 TypeScript 用户消费。为了让这些类型定义在较老的 TypeScript 编译器中依然可用仓库专门设置了require/old-ts目录并配套了test-old-ts测试目标。本文以require/old-ts/README.md为线索结合 Makefile、lib/shared/types.ts 与相关配置完整剖析这套旧版 TypeScript 回归测试的动机、实现与运行方式读者可据此复现验证也能把同样的思路迁移到自己的开源库中。一、背景esbuild 的类型定义从何而来esbuild 的 JavaScript APIbuild、transform、serve、context等类型声明并不是手写在每个 npm 包里的而是统一维护在 lib/shared/types.ts 一个源文件中。正如 lib/README.md 所述This directory contains the TypeScript code that becomes the JavaScript API code in theesbuildandesbuild-wasmpackages. Its automatically built during the build process for those packages.也就是说类型定义源文件会在make platform-neutral、make platform-wasm等构建流程中被打包进发布产物。lib/shared/types.ts全文约 720 行定义了BuildOptions、TransformOptions、ServeOptions、Message、Location、Metafile等完整 API 类型例如lib/shared/types.ts#L10-L95 的CommonOptions汇总了sourcemap、format、target、minify、jsx、define、logLevel等通用配置lib/shared/types.ts#L116-L177 的BuildOptions补充了bundle、splitting、outfile、outdir、external、loader、plugins等打包专属选项lib/shared/types.ts#L226-L235 的BuildResult使用了ProvidedOptions[write] extends false ? never : undefined这类条件类型根据传入的write选项精确推导返回结构中outputFiles字段的存在性。正是因为类型定义面向的是所有TypeScript 用户它就必须在尽量老的编译器版本上也能通过语法与类型检查否则下游用户可能因为SyntaxError或类型错误而无法使用 esbuild 的 API。二、问题类型定义容易悄悄用上新语法类型定义文件由项目维护者编写日常开发与自测通常使用最新版 TypeScript。这带来一个隐蔽风险维护者可能无意中使用了旧版 TypeScript 尚不支持的语法或类型特性如较新的关键字、较新的条件类型写法、新版内置工具类型等。在最新编译器下一切正常但老用户一升级 esbuild 包就会遇到编译失败体验很差。require/old-ts/README.md只有一句话却精准概括了这套目录的用途This is used to ensure that our type definitions dont accidentally use newer features that break in older versions of TypeScript.即用一套固定老版本的 TypeScript 去编译类型定义作为回归测试防止新特性悄悄溜进.d.ts。三、方案require/old-ts 目录的组成require/old-ts是一个极简的独立 Node 工程仅用于固定旧版 TypeScript 工具链{ dependencies: { typescript: 3.5.3 } }对应的 require/old-ts/package-lock.json 中锁定了typescript3.5.3并声明其node 4.2.0的引擎要求。选型 3.5.3 的意图很明确它是 2019 年发布的一个被广泛使用的稳定版本把它作为兼容性下限来把关类型定义能覆盖绝大多数的存量用户环境。仓库中还有一个细节佐证了这种以老版本为护栏的取向主类型检查用的 lib/package.json 依赖typescript6.0.2与require/old-ts形成了新版本做主检、老版本做回归的双层防护。四、核心实现Makefile 中的 test-old-ts 目标整套测试逻辑集中在一个 Makefile 目标里见 Makefile#L142-L149require/old-ts/node_modules: cd require/old-ts npm ci test-old-ts: | require/old-ts/node_modules rm -fr scripts/.test-old-ts mkdir scripts/.test-old-ts cp lib/shared/types.ts scripts/.test-old-ts/main.d.ts cd scripts/.test-old-ts ../../require/old-ts/node_modules/.bin/tsc *.d.ts rm -fr scripts/.test-old-ts逐步拆解它的执行流程准备依赖test-old-ts声明前置目标require/old-ts/node_modules首次运行时执行cd require/old-ts npm ci按 lockfile 精确安装typescript3.5.3npm ci而非npm install保证每次测试的环境完全一致。复制类型定义把lib/shared/types.ts复制为临时目录scripts/.test-old-ts/main.d.ts。复制成.d.ts后缀并改名为main是为了让旧版tsc把它当作一个独立的声明文件参与编译。用旧编译器编译在scripts/.test-old-ts内调用../../require/old-ts/node_modules/.bin/tsc *.d.ts用 TypeScript 3.5.3 的tsc直接编译这份声明文件。只要其中出现任何 3.5.3 无法解析的语法或类型构造tsc就会报错测试随即失败。清理现场无论成败最后rm -fr scripts/.test-old-ts删除临时目录保证不污染工作区、不产生构建残留。这条链路的关键点在于test-old-ts验证的是语法与类型层面的可编译性而不是语义等价性——它不关心 esbuild 运行时行为只保证.d.ts在旧编译器下能被干净地解析。五、为什么选 TypeScript 3.5兼容基线的权衡选择 3.5.3 作为最老被测版本并非随意而是对维护成本与覆盖范围的平衡太老如 2.x会引入过多历史兼容负担且与 esbuild 类型定义实际用到的语法如条件类型、Record工具类型等完全不匹配测试将失去区分度太新如 4.x、5.x则无法拦住真正的老用户痛点护栏形同虚设。3.5.3 恰好位于支持大部分现代类型语法与能暴露较新语法特性的交界处。同时由于依赖被npm ci锁定无论何时运行make test-old-ts拿到的都是同一份编译器二进制结果可稳定复现。从lib/shared/types.ts的实际内容看类型定义大量使用了Recordstring, ...、条件类型extends ... ? ... : ...、可选链外的联合类型推导等构造这些在 3.5 中均可解析恰好验证了该基线选择的合理性。六、与仓库其他类型检查机制的配合test-old-ts并非孤立的类型保障它与仓库中的其他检查共同构成三层防线机制工具链覆盖范围位置test-old-tsTypeScript 3.5.3类型定义文件.d.ts的向后兼容性Makefile#L145-L149lib-typecheck-node最新版 TypeScript6.0.2lib目录全部 TypeScript 源码的类型自检Makefile#L156-L157、lib/tsconfig.jsonts-type-tests仓库内 node_modules通过scripts/ts-type-tests.js对构建出的esbuild包做类型行为断言scripts/ts-type-tests.js三者分工明确lib-typecheck-node保证新编译器下类型定义自身正确ts-type-tests例如 scripts/ts-type-tests.js#L13-L19 中esbuild.buildSync({})、esbuild.build({})的用例验证类型行为与运行时结果一致而test-old-ts专门保证老编译器下不炸。lib/tsconfig.json中module: CommonJS、target: es2017、strict: true等选项也说明主类型检查使用的是严格的现代配置与老版本回归测试形成互补。七、如何本地复现验证在当前仓库根目录下即可执行# 仅运行旧版 TypeScript 兼容性测试 make test-old-ts # 运行完整的 lib 类型检查含新版本自检 make lib-typecheck流程为先触发npm ci安装 3.5.3再复制类型定义、用旧版tsc编译、最后清理临时目录。若lib/shared/types.ts后续引入了 3.5.3 不支持的语法例如更新的内置类型或语法糖make test-old-ts会立刻以tsc报错的形式拦截从而在发布前发现兼容性回归。开发者在修改lib/shared/types.ts时也可以先跑一遍make test-old-ts作为快速反馈。八、总结require/old-ts用不到十行 Makefile 规则就为 esbuild 的类型定义建立了一条最老版本护栏以锁定的 TypeScript 3.5.3 编译.d.ts用最小成本拦截向后兼容性回归。这套模式对任何面向广泛 TypeScript 用户群的开源库都具有直接借鉴价值——维护一份老编译器编译测试比依赖维护者自律更可靠。对 esbuild 而言它保障了lib/shared/types.ts这份 720 行的 API 声明在各类用户环境中都能被稳定解析是极速打包器在类型体验层面同样可靠的底气来源。赞分享构建工具前端【免费下载链接】esbuildAn extremely fast bundler for the web项目地址https://gitcode.com/GitHub_Trending/es/esbuild点击查看免费下载相关推荐OpenChamber 1.10.1 发布详解一键 Git 同步与 Stash 管理实战指南OpenChamber 1.10.1 发布详解一键 Git 同步与 Stash 管理实战指南 OpenChamber 1.10.12026 05 06 发布AI Agent人工智能代码智能体交互助手Blockly TypeScript 类型测试以编译即通过保障 API 类型定义的向后兼容Blockly TypeScript 类型测试以编译即通过保障 API 类型定义的向后兼容 TypeScript 测试 packages/blockly/t前端低代码UI组件Skel常见问题解答开发者必知的10个解决方案Skel常见问题解答开发者必知的10个解决方案 Skel作为一款轻量级响应式框架在开发过程中难免会遇到各种问题。本文整理了开发者最常遇到的10个问题及解决方前端上一篇CANN动态MX量化算子API下一篇10分钟上手Douyin-Bot人脸识别黑科技从截图到高颜值检测全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考