ESM 与 CJS 双格式包输出

ESM（ECMAScript 模块）是官方的 JavaScript 模块标准，使用 import 和 export 语法。ESM 可以进行静态分析——打包工具能够在构建时准确确定使用了哪些导出内容，从而实现摇树优化。现代浏览器和 Node.js 都原生支持 ESM。

CJS（CommonJS）使用 require() 和 module.exports 语法。它是 Node.js 最初的模块系统，目前仍然用于兼容较旧的 Node.js 环境、Jest（历史上使用 CJS）以及使用 require() 的代码。CJS 会动态求值，因此更难进行摇树优化。

现代 npm 包应同时发布 ESM 和 CJS，以最大限度地提高兼容性。ESM 使用者（Vite、Next.js、现代打包工具）可以使用支持摇树优化的导入方式。CJS 使用者（较旧的 Node.js 脚本、未配置的 Jest）可以获得 require() 兼容性。package.json 的 exports 字段会告诉 Node 和打包工具应使用哪种格式。

package.json 中的 exports 字段是定义条件入口点的现代方式。例如：{ '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }。打包工具和 Node.js 12+ 会读取 exports，以自动选择正确的格式。

较旧的工具无法理解 exports 字段。为确保兼容性，还应设置：指向 CJS 输出的 main（旧版 Node require 的回退入口），以及指向 ESM 输出的 module（供 webpack/Rollup 使用的提示，虽非标准但得到广泛支持）。现代工具优先使用 exports，旧版工具则回退到 main/module。

在 package.json 中设置 "type": "module" 后，包中的所有 .js 文件都会被视为 ESM。如果发布双格式包，就需要使用明确的扩展名：当 type 为 module 时，使用 .mjs 表示 ESM 文件，使用 .cjs 表示 CJS 文件，反之亦然。tsup 会自动处理这一点。

显式使用 .mjs（ESM）和 .cjs（CJS）文件扩展名，无论 type 字段如何设置，都能明确标记格式。这样可以避免歧义。当 format 为 ['esm', 'cjs'] 且未设置 type 字段时，tsup 可以输出：index.js（ESM）和 index.cjs（CJS），这符合最常见的约定。

当一个包同时提供 ESM 和 CJS 格式时，使用者的打包工具可能会在同一进程中加载两个版本——例如主应用加载 ESM 版本，而 Jest 测试加载 CJS 版本。如果包包含模块级状态（例如 React 上下文），两个实例会分别拥有独立状态。这就是双格式包陷阱。

要缓解这一陷阱：不要在库中保存模块级状态（不使用单例模式）；精确使用 exports 条件，确保只加载一种格式；并说明测试应配置其打包工具使用 ESM。这个陷阱主要影响包含共享单例的库。

构建后请验证两种格式都能正常工作。测试 CJS：node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)"。测试 ESM：node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)"。发布前，两种格式都应能正常解析且不产生错误。

exports 字段支持多个入口点：{ '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }。这样，使用者可以从 'your-lib' 或 'your-lib/utils' 导入，并获得正确的格式。

库的 package.json 中的 exports 字段主要有什么作用？

ESM 使用 import/export，并支持摇树优化。CJS 使用 require() 以兼容 Node.js。通过 package.json 的 exports 字段，并配合 import/require 条件，同时发布两种格式。旧版回退方式：main（CJS）和 module（ESM）。使用 .mjs/.cjs 扩展名或 type: module 明确标记格式。构建后使用 Node CLI 测试两种格式。请注意包含单例状态时的双格式包陷阱。