在 package.json 中配置 exports 字段,通过定义主入口、条件分支和子路径映射来精确控制模块的解析行为。核心做法是设置顶层键指向默认文件,并在内部使用 import 或 require 条件区分环境,同时利用通配符处理子目录导入。

如何配置主入口以兼容 CommonJS 和 ES Modules?
通过为 import 和 require 分别指定不同的文件路径,可以实现对两种模块系统的兼容支持。通常将 ES Module 文件设为默认值,而将 CommonJS 文件作为后备选项。

{
"name": "my-package",
"version": "1.0.0",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
}
}
上述配置中,"." 代表包的主入口。当工具(如 Webpack 或 Vite)使用 import 语法时,会解析到 ./dist/index.mjs;若使用 require 或 Node.js 的 require() 调用,则解析到 ./dist/index.cjs。这种写法确保了在不同构建环境下都能正确加载对应的实现。
如何安全地暴露子路径而不泄露内部结构?
使用通配符 "./utils/*" 可以精确映射子目录下的文件,同时防止访问未列出的其他文件。这种方式比直接导出整个目录更安全,因为它显式声明了哪些子模块是可用的。
使用 Husky 将 pre-commit、pre-push 和 commit-msg 检查集成到仓库中,以便代理和开发人员在更改离开工作站之前运行相同的本地防护措施。

{
"name": "my-package",
"version": "1.0.0",
"exports": {
".": "./dist/index.mjs",
"./utils": "./dist/utils/index.mjs",
"./utils/*": "./dist/utils/*.mjs"
}
}
在这个例子中,"./utils/*" 允许导入 my-package/utils/helper.mjs 等具体文件,但无法导入 my-package/internal/secret.mjs,除非显式添加该路径。这种细粒度的控制避免了意外暴露内部实现细节,提升了包的封装性。
当子路径匹配失败时会发生什么?
如果尝试导入未在 exports 中明确定义的路径,Node.js 和现代打包工具会抛出 ERR_PACKAGE_PATH_NOT_EXPORTED 错误。这意味着只有被显式列出的路径才是可访问的,未列出的路径将被拒绝。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南










