如何发布同时兼容BrowserJS、NodeJS、ts-node并支持Webpack Tree Shaking的TypeScript编写Node.js库

你目前遇到的核心矛盾是ES模块的Tree Shaking优势与NodeJS/ts-node默认兼容性的冲突，但完全不需要放弃ES模块带来的Tree Shaking能力——通过双模块发布策略，再结合TypeScript 4.5+的新特性，就能同时满足浏览器端的体积优化需求和NodeJS/ts-node的运行要求。

为什么当前方案会报错？ #

先复盘你列出的模块兼容性现状：

• ES模块能完美适配Webpack的Tree Shaking，但NodeJS默认以CommonJS模式运行，遇到export语法会直接抛出语法错误（就是你运行NodeJS.js时看到的报错）；
• ts-node对ES模块的原生支持原本有限，尤其是在未设置"type": "module"的项目中，会触发加载警告。

你的库当前只发布了ES模块版本，自然无法兼容NodeJS和ts-node的默认使用场景。

核心解决方案：双模块发布（CommonJS + ES模块） #

这是前端社区解决这类兼容性问题的通用方案，既能保留ES模块的Tree Shaking能力，又能让NodeJS/ts-node用户正常使用。具体步骤如下：

1. 编译产出两种模块版本 #

在你的库的构建流程中，同时编译出两个版本的代码：

• ES模块版本：保持现有配置（target ES2020，module ESNext），输出到dist/esm目录，用于Webpack等打包工具实现Tree Shaking；
• CommonJS版本：调整TypeScript配置（target ES2015+，module CommonJS），输出到dist/cjs目录，用于NodeJS和ts-node环境。

你可以用两个独立的tsconfig.json文件分别控制两种编译：

• tsconfig.esm.json（ES模块编译配置）：

  {
    "compilerOptions": {
      "target": "ES2020",
      "module": "ESNext",
      "outDir": "./dist/esm",
      "declaration": true,
      "declarationDir": "./dist/types"
    },
    "include": ["src/**/*"]
  }
  

• tsconfig.cjs.json（CommonJS编译配置）：

  {
    "compilerOptions": {
      "target": "ES2015",
      "module": "CommonJS",
      "outDir": "./dist/cjs",
      "declaration": true,
      "declarationDir": "./dist/types"
    },
    "include": ["src/**/*"]
  }
  

2. 配置package.json的入口字段 #

在库的package.json中添加以下配置，让不同工具自动选择对应的模块版本：

{
  "name": "@yamato-daiwa/es-extensions",
  "main": "./dist/cjs/index.js", // NodeJS/ts-node默认加载的CommonJS入口
  "module": "./dist/esm/index.js", // Webpack/Rollup优先加载的ES模块入口（保证Tree Shaking）
  "types": "./dist/types/index.d.ts", // 共享的TypeScript类型定义
  // 可选：NodeJS 12+支持的exports字段，更精准控制模块入口
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    }
  }
}

TypeScript 4.5的新特性能帮上什么忙？ #

TypeScript 4.5确实引入了两个关键特性，进一步优化模块兼容性：

1. 原生支持package.json的exports字段 #

TypeScript 4.5开始能够识别package.json中的exports配置，自动根据用户的导入方式（import或require）匹配对应的模块版本和类型定义。这意味着用户不管是在ES模块项目还是CommonJS项目中使用你的库，TypeScript都能正确解析类型。

2. 改善ts-node的ES模块支持 #

配合ts-node v10+版本，TypeScript 4.5让ts-node对ES模块的支持更加稳定。如果用户的项目设置了"type": "module"，或者使用.mts扩展名，ts-node可以直接加载你的库的ES模块版本；而对于未开启"type": "module"的项目，会自动加载CommonJS版本，不会再出现加载警告。

不过双模块发布仍然是更稳妥的方案，因为它能兼容所有NodeJS版本和ts-node的使用场景，不需要用户额外调整项目配置。

验证你的复现场景 #

调整后，你的复现项目会得到以下预期结果：

• 浏览器构建（Webpack Production）：Webpack会优先读取package.json的module字段，加载ES模块版本，Tree Shaking正常生效，产出的BrowserJS.js仍然是你预期的精简代码；
• NodeJS运行：NodeJS会读取main字段加载CommonJS版本，运行NodeJS.js时不会再出现export语法错误；
• ts-node运行：ts-node会自动匹配对应的模块版本，加载警告消失，import { isUndefined } from "@yamato-daiwa/es-extensions"能正常执行。

额外注意点 #

• 不需要让用户将你的库加入Webpack的externals列表——双模块发布后，Webpack会自动处理模块加载，用户无需额外配置；
• 确保你的库的所有依赖也兼容双模块环境，或者至少在CommonJS和ES模块中都能正常运行。

内容的提问来源于stack exchange，提问作者Takeshi Tokugawa YD