模块解析与 ESM/CJS 互操作：exports 字段、bundler 模式与双包问题

Node 运行时：看 package.json 的 type 字段与文件扩展名决定格式
TypeScript  ：看 tsconfig 的 module / moduleResolution 决定如何找类型
打包器       ：有自己的解析算法（vite/rollup/webpack 各有差异）

// tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",          // 与 moduleResolution 联动
    "moduleResolution": "nodenext" // 或 bundler
  }
}

bundler 模式允许：import "./foo"（省略扩展名、目录 index 解析）
node16 模式强制：import "./foo.js"（ESM 必须带扩展名）

// package.json
{
  "name": "my-lib",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": "./dist/utils.js"
  }
}

条件（condition）按声明顺序匹配，命中即止：
  types   → 类型（必须放最前，否则被忽略）
  import  → ESM 入口
  require → CJS 入口
  default → 兜底

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

1. ESM 可以 import CJS：默认导出 = module.exports
2. CJS 不能 require ESM（Node 20+ 支持 require(esm) 的实验特性除外）
3. ESM 无 __dirname / __filename / require → 用 import.meta.url

import { fileURLToPath } from "node:url"
import { dirname } from "node:path"

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)

// CJS 文件里加载 ESM 包，只能异步
async function load() {
  const { render } = await import("some-esm-only-lib")
  return render()
}

ESM import CJS 时，Node 用 cjs-module-lexer 静态分析 CJS 的命名导出
动态构造的导出（module.exports[k] = v）可能无法被识别
→ 只能拿到 default，具名导入会 undefined

1. instanceof 失效：两份 class 定义不同
2. 单例失效：模块级状态（缓存、连接池）出现两份
3. 符号/枚举不相等：Symbol() 与枚举比较失败

// 应用同时 require 与 import 了 my-lib
const a = require("my-lib")
const b = await import("my-lib")
a === b.default          // false
new a.Client() instanceof b.Client   // false

方案一：只发 ESM（现代项目首选，Node 20+ / 打包器都支持）
方案二：CJS 为主 + ESM 薄封装（ESM 层 re-export CJS）
方案三：状态放到单一来源（如 globalThis 上的符号键）
方案四：用 exports 条件保证同环境只命中一份

{
  "type": "module"   // .js 视为 ESM
  // 或 "type": "commonjs"（默认）→ .js 视为 CJS
}

// ESM 包
{ "type": "module", "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } } }

// 双格式包
{
  "type": "commonjs",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

moduleResolution: "bundler" 允许：
  import "./foo"      省略扩展名
  import "@/utils"    路径别名（配合 paths）
  import "./dir"      目录 index 解析

// bundler 模式下合法，nodenext 下报错
import { helper } from "./helper"   // 缺 .js 扩展名

// tsconfig.json（应用：bundler）
{ "compilerOptions": { "module": "esnext", "moduleResolution": "bundler" } }

// tsconfig.lib.json（库：nodenext）
{ "compilerOptions": { "module": "nodenext", "moduleResolution": "nodenext" } }

// tsup.config.ts
import { defineConfig } from "tsup"

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,
  clean: true,
  outExtension: ({ format }) => ({ js: format === "esm" ? ".mjs" : ".cjs" }),
})

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "files": ["dist"]
}

{
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    }
  }
}

# 用 arethetypeswrong 检查导出与类型的匹配
npx @arethetypeswrong/cli --pack .

阻塞项：依赖里是否有 ESM-only 且只能 require 的包
阻塞项：是否有 __dirname / require.resolve 等 CJS 专属 API
阻塞项：测试框架、构建工具、部署环境是否支持 ESM