包的入口

在包的 package.json 文件中，两个字段可以定义包的入口点："main" 和 "exports"。 这两个字段都适用于 ES 模块和 CommonJS 模块入口点。

所有版本的 Node.js 都支持 "main" 字段，但它的功能有限：它只定义了包的主要入口点。

"exports" 提供了 "main" 的现代替代方案，允许定义多个入口点，支持环境之间的条件入口解析，并防止除了 "exports" 中定义的入口点之外的任何其他入口点。 此封装允许模块作者清楚地为他们的包定义公共接口。

对于针对当前支持的 Node.js 版本的新包，建议使用 "exports" 字段。 对于支持 Node.js 10 及以下的包，"main" 字段是必需的。 如果同时定义了 "exports" 和 "main"，则在支持的 Node.js 版本中，"exports" 字段优先于 "main"。

条件导出可以在 "exports" 中用于为每个环境定义不同的包入口点，包括包是通过 require 还是通过 import 引用。 有关在单个包中同时支持 CommonJS 和 ES 模块的更多信息，请参阅双 CommonJS/ES 模块包章节。

现有包引入 "exports" 字段将阻止包的消费者使用任何未定义的入口点，包括 package.json（例如 require('your-package/package.json')。 这可能是一个突破性的变化。

为了使 "exports" 的引入不间断，请确保导出每个以前支持的入口点。 最好明确指定入口点，以便包的公共 API 定义明确。 例如，以前导出 main、lib、feature 和 package.json 的项目可以使用以下 package.exports：

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./lib/index": "./lib/index.js",
    "./lib/index.js": "./lib/index.js",
    "./feature": "./feature/index.js",
    "./feature/index": "./feature/index.js",
    "./feature/index.js": "./feature/index.js",
    "./package.json": "./package.json"
  }
}

或者，项目可以选择使用导出模式导出带有和不带有扩展子路径的整个文件夹：

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./lib/*": "./lib/*.js",
    "./lib/*.js": "./lib/*.js",
    "./feature": "./feature/index.js",
    "./feature/*": "./feature/*.js",
    "./feature/*.js": "./feature/*.js",
    "./package.json": "./package.json"
  }
}

以上为任何次要包版本提供向后兼容性，包的未来重大更改可以适当地将导出限制为仅暴露的特定功能导出：

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./feature/*.js": "./feature/*.js",
    "./feature/internal/*": null
  }
}

In a package's package.json file, two fields can define entry points for a package: "main" and "exports". Both fields apply to both ES module and CommonJS module entry points.

The "main" field is supported in all versions of Node.js, but its capabilities are limited: it only defines the main entry point of the package.

The "exports" provides a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports". This encapsulation allows module authors to clearly define the public interface for their package.

For new packages targeting the currently supported versions of Node.js, the "exports" field is recommended. For packages supporting Node.js 10 and below, the "main" field is required. If both "exports" and "main" are defined, the "exports" field takes precedence over "main" in supported versions of Node.js.

Conditional exports can be used within "exports" to define different package entry points per environment, including whether the package is referenced via require or via import. For more information about supporting both CommonJS and ES modules in a single package please consult the dual CommonJS/ES module packages section.

Existing packages introducing the "exports" field will prevent consumers of the package from using any entry points that are not defined, including the package.json (e.g. require('your-package/package.json'). This will likely be a breaking change.

To make the introduction of "exports" non-breaking, ensure that every previously supported entry point is exported. It is best to explicitly specify entry points so that the package's public API is well-defined. For example, a project that previous exported main, lib, feature, and the package.json could use the following package.exports:

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./lib/index": "./lib/index.js",
    "./lib/index.js": "./lib/index.js",
    "./feature": "./feature/index.js",
    "./feature/index": "./feature/index.js",
    "./feature/index.js": "./feature/index.js",
    "./package.json": "./package.json"
  }
}

Alternatively a project could choose to export entire folders both with and without extensioned subpaths using export patterns:

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./lib/*": "./lib/*.js",
    "./lib/*.js": "./lib/*.js",
    "./feature": "./feature/index.js",
    "./feature/*": "./feature/*.js",
    "./feature/*.js": "./feature/*.js",
    "./package.json": "./package.json"
  }
}

With the above providing backwards-compatibility for any minor package versions, a future major change for the package can then properly restrict the exports to only the specific feature exports exposed:

{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./feature/*.js": "./feature/*.js",
    "./feature/internal/*": null
  }
}