正确配置exports字段是让npm包被现代工具（如Vite、Webpack 5+、Node.js 12.20+/14.13+）正确识别ESM入口的关键，它决定import行为及Node.js的ESM解析规则；双模式包推荐用exports精确映射import/require入口，并保留main/module作兼容回退。
在发布支持 ESModule 的 npm 包时，正确配置 exports 字段是让模块被现代工具（如 Vite、Webpack 5+、Node.js 12.20+/14.13+）正确识别 ESM 入口的关键。它不仅影响 import 行为，还决定是否触发 Node.js 的 ESM 解析规则（比如自动匹配 .js → .mjs 或根据 "type": "module" 切换解析逻辑）。
明确包的模块类型和目标环境
先确认你的包是纯 ESM、兼容 CJS/ESM，还是需双包输出：
-
纯 ESM 包：不提供
require()入口，package.json中必须包含"type": "module"，且所有源码用.js（或.mjs）按 ESM 语法编写； -
双模式包（推荐多数情况）：同时提供 ESM 和 CommonJS 入口，通过
exports精确映射，不依赖"type": "module"，兼容更广（包括旧版 Webpack、Jest 等）； -
注意：不要混用
"type": "module"+exports指向.cjs文件，Node.js 会报错。
exports 字段的最小可用结构（双模式示例）
以下是一个兼顾 Node.js、Vite、Webpack 的典型 exports 配置（假设入口文件为 index.js 和 dist/index.mjs）：
{
"name": "my-lib",
"type": "commonjs",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"./package.json": "./package.json"
}
}
说明：
立即学习“Java免费学习笔记（深入）”；
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
"."表示包的默认入口（即import "my-lib"或require("my-lib")）； -
"import"对应 ESM 加载器（如import、Vite、Node.js ESM 模式）； -
"require"对应 CommonJS 加载器（如require()、Webpack 4、Node.js CJS 模式）； -
"./package.json"显式放行，避免exports封闭后读取失败（尤其被其他工具如 TypeScript 引用时）； -
"type": "commonjs"是安全默认，即使你有 ESM 输出也不必设为"module"。
支持子路径导入（如 import { foo } from "my-lib/utils"）
若希望用户能直接导入内部模块，需在 exports 中显式声明子路径：
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"./utils": {
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
},
"./utils/*": {
"import": "./dist/utils/*.mjs",
"require": "./dist/utils/*.cjs"
},
"./package.json": "./package.json"
}
注意：
- 子路径必须以
"./"开头，否则会被视为外部依赖； - 通配符
*需配合"./xxx/*"形式，且只在 Node.js 14.13+ / 16.14+ 支持； - Vite/Webpack 通常能识别这种映射，但部分老 bundler 可能忽略
exports，此时仍需靠module/main回退。
构建与发布前检查要点
确保实际发布的 dist/ 目录中存在对应文件，并验证解析行为：
- 运行
node --experimental-conditional-exports -e "import('my-lib')"测试 ESM 导入； - 运行
node -e "require('my-lib')"测试 CJS 导入； - 用
npx ts-node或vite dev验证 TypeScript/Vite 下能否正确解析类型和代码； - 检查
npm pack打出的 tarball 是否包含dist/文件及package.json的exports字段； - 避免在
exports中引用未发布的路径（如src/），否则安装后会报ERR_PACKAGE_PATH_NOT_EXPORTED。
不复杂但容易忽略：exports 不是“锦上添花”，而是现代 JS 生态里控制模块可见性的核心开关。配错会导致用户 import 失败、类型丢失、tree-shaking 失效，甚至整个包无法在 ESM 环境下工作。
