package.json exports 定义双入口模块方法

本文详解如何通过 package.json 的 exports 字段优雅实现 Node.js 模块的“双重入口”——让同一个 npm 包无缝支持 ESM（import）和 CommonJS（require），无需构建工具介入，兼顾现代环境（Node.js 12+、Vite、Webpack 5）与旧版生态（Node.js 10–14、Webpack 4），并通过 type: "module"、条件导出、手写 .cjs/.mjs 入口文件及兼容性字段（main/module）协同工作，确保 API 一致、逻辑复用、零配置降级，是构建高兼容性 TypeScript/JavaScript 库的实用范式。

通过 package.json 的 exports 字段定义“双重入口”模块，核心是让同一包同时支持 ESM（现代浏览器/Node.js）和 CommonJS（旧版 Node.js、某些构建工具），且不依赖构建步骤。关键在于正确声明条件导出（conditional exports），并确保入口文件在两种环境下的行为一致。

明确双重入口的目标场景

所谓“双重入口”，通常指：

• ESM 入口：供 import 使用，支持顶层 await、动态 import()，应为纯 ESM 格式（无 require 或 module.exports）
• CJS 入口：供 require() 使用，兼容 Node.js 10–14 及 Webpack 4 等老工具
• 二者导出的 API 表面一致（如相同函数名、类型签名），内部可按需做轻量适配（如默认导出包装）

配置 exports 字段的最小可行结构

在 package.json 中使用 "exports" 对象，按条件匹配环境。推荐如下写法：

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

说明：

• "type": "module" 声明包默认为 ESM，避免 Node.js 将 .js 文件误判为 CJS
• "import" 条件匹配所有 ESM 加载场景（import、import()、type: "module" 的 package.json）
• "require" 条件匹配所有 CJS 加载场景（require()、Webpack 4 默认模式）
• "main" 和 "module" 是向后兼容字段，供不支持 exports 的旧工具（如 Webpack 4、Rollup 插件）降级使用

准备两个物理入口文件（无需构建时生成）

不必用打包器生成 .cjs 和 .mjs——手写即可，保持轻量：

• dist/index.cjs：使用 module.exports = 导出，默认导出可包装为命名导出对象
• dist/index.mjs：使用 export default 和 export const xxx，若需兼容 CJS 用户的 require("pkg").default，可在 ESM 入口显式导出 default
• 两者都应引用同一份逻辑（如 ./lib/core.js），仅做导出形式转换，避免逻辑重复

示例 dist/index.cjs：

const { foo, bar } = require('../lib/core.js');
module.exports = { foo, bar };
module.exports.default = { foo, bar };

示例 dist/index.mjs：

import { foo, bar } from '../lib/core.js';
export { foo, bar };
export default { foo, bar };

验证跨平台兼容性

手动测试三类典型调用方式：

• Node.js ESM：node --experimental-specifier-resolution=node -e "import('your-pkg').then(console.log)"
• Node.js CJS：node -e "console.log(require('your-pkg'))"
• Webpack 5（开箱即用）或 Vite（默认 ESM）中 import 和 require 混用

注意：若发布到 npm，确保 files 字段包含 dist/ 目录，且未意外忽略 .cjs 或 .mjs 扩展名。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。