如何开发兼容多运行环境的通用JavaScript/TypeScript库

你需要的类create-react-app的库开发工具确实存在，不需要手动维护复杂的ts、webpack配置就能覆盖所有你提到的运行场景。

首选零配置构建工具 #

直接用专门针对TS库优化的构建工具，不需要写任何构建配置就能生成全兼容的产物：

• tsup：基于esbuild驱动的轻量构建工具，核心优势如下：
  • 开箱即用支持TypeScript，自动生成类型声明文件，不需要手动调整tsconfig.json的复杂配置
  • 一行命令即可同时输出CommonJS、ES Module、UMD三种标准格式产物，自动适配require引入、import引入、浏览器直接引入等场景
  • 加--target es5参数即可自动做语法降级，适配不支持ES6的旧版浏览器
  • 自动生成package.json所需的main、module、types、exports等核心字段，确保webpack、vite、tsc、ts-node、create-react-app等所有构建工具都能正确识别你的包
• unbuild：另一款零配置构建工具，比tsup支持更多自定义场景，默认也能输出全格式兼容产物。

核心注意事项 #

只要遵守以下规则，就能避免99%的跨环境运行问题：

• 不要直接发布TypeScript源码，必须编译为JS产物后再发布，同时附带对应的.d.ts类型声明文件
• 纯函数逻辑不要隐式依赖任何平台专属API（比如node的fs模块、浏览器的window对象），如果确实需要平台专属能力，要做动态兼容判断
• 保留构建工具自动生成的exports字段，它会自动处理不同引入方式、不同子路径引入的路径映射，完美支持部分引入场景

全场景自动化测试方案 #

不需要手动在每个环境下测试，用极简配置即可覆盖所有场景：

• 单元测试用vitest，自带node、jsdom双环境支持，一行命令即可同时跑node端和浏览器端的单元用例
• 加一个简单的本地兼容性校验脚本，发布前自动模拟所有核心场景：用CommonJS require引入包执行、用ES Module import引入包执行、在ts-node中引入执行、在空TS项目中引入编译，所有校验通过再发布
• 不需要单独测试create-react-app等框架场景，只要你的包符合CommonJS/ES Module规范、package.json字段配置正确，所有符合前端生态规范的构建工具都能正常识别使用

最简开发流程 #

整个开发流程不需要任何样板代码，只需要三步：

1. 初始化空项目后，新建src/index.ts编写你的TS代码
2. 在package.json的scripts中加入两行命令：

   "build": "tsup src/index.ts --format cjs,esm,umd --dts --target es5",
   "test": "vitest run --environment node && vitest run --environment jsdom"
   

3. 开发完成后执行npm run build，校验测试通过即可直接发布。

内容的提问来源于stack exchange，提问作者Pavol Hejný