投稿
  1. 极客之音首页
  2. 前端开发

Node.js 包编写指南#1：模块系统与入口文件

小半 • • 前端开发 • 阅读 270

本指南并不是“从 0 到 1 教你如何创建并发布一个 npm 包”的教程，也没有介绍任何三方打包工具的使用，而是仅仅从 Node.js 包编写者的角度，学习和理解 Node.js 运行时行为。

这个指南计划发 2 篇，这是第 1 篇。

  • #1: 模块系统与入口文件（本篇）
  • #2: 模块互操作性、双模块包以及运行时字段

什么是包？

对 Node.js 来说， 包（Package）就是一个包含 package.json 文件的目录。package.json 文件使用 JSON 格式描述 Node.js 项目的基本信息。

一个包内还支持包含 node_modules 目录，存放当前包所依赖的其他包。

模块系统

Node.js 支持两种模块系统：CommonJS 和 ES Module。CommonJS 模块语法是在 Node.js 创建之初就支持的，ES Module 则是 JavaScript 官方模块语法，Node.js 也在 v14.17.0/v12.22.0 版本[1]中正式支持了。

启用 ES Module 模块语法

Node.js  中，有 2 种方式将一个文件视为使用 ES Module 文件：

  1. 以 .mjs 后缀的文件。或者
  2. 在 package.json 文件中将 type 字段显式指定为 "module"。如此，当前项目所有的 .js 文都会被认为是 ES Module 文件

推荐始终在 package.json 中指定 type 字段

package.json 文件中的 type 字段用于定义项目中 .js 文件所使用的模块语法。当 type 字段值为 "module" 时，项目内所有 .js 文件都会被视为 ES  Module 文件。

// package.json
{
  "type": "module"
} 
# In same folder as preceding package.json
node my-app.js # Runs as ES module 

同理，当将 type 字段值为 "commonjs" 时，项目内所有 .js 文件都会被视为 CommonJS 文件。

// package.json
{
  "type": "commonjs"
} 
# In same folder as preceding package.json
node my-app.js # Runs as CommonJS 

注意：虽然目前 Node.js 会将 .js 默认视为 CommonJS 文件（这是因为 type 字段默认值即 "commonjs"），但未来默认模块语法会迁移至 ES Module（即 type 字段默认值会改为 "module"），对齐 JavaScript 官方模块语法。因此，Node.js 官方团队推荐始终在 package.json 中指定 type 字段。

.mjs & .cjs 文件

对于那些旧版本的 CommonJS 包，为了向后兼容，同时避免修改整个软件包内的文件，也可以通过将文件后缀改成 .cjs来解决。

对 Node.js 来说：

  1. 不管当前项目的 package.json 的 type 字段值是什么，.cjs 都会被视为 CommonJS 文件
  2. 不管当前项目的 package.json 的 type 字段值是什么，.mjs 都会被视为 ES Module 文件

包的入口文件

当你编写的包作为别人项目的三方包加载时，Node.js 是通过包根目录下的 package.json 文件，查看要加载的入口文件。由于历史原因，入口文件可以通过 2 个字符指定。分别是：

  • "main"，和
  • "exports"

"main" 是 Node.js 创建之初就支持的指定入口文件的字段。在 Node.js 没支持 ES Moudle 之前，"main" 字段始终对应项目中的一个 CommonJS 文件；在 Node.js 支持 ES Module 之后（假设，为 package.json 指定 "type": "module"），"main" 指定的就是 ES Module 文件了。

“exports” 字段

"exports" 字段是跟 ES Module 模块语法一起引入的，在 v14.13.0/v12.20.0 版本[2]中就正式支持了。Node.js 引入 "exports"字段是替代 "main" 字段。创建新包时，推荐都使用 "exports"字段：

{
  "exports": "./index.js"
} 

当前，除了 Node.js，现代构建工具都支持 "exports" 字段。而对于仍旧使用旧版本 Node.js 或相关构建工具的项目，可以通过同时指定 "exports" 和 "main" 字段来实现功能兼容。

{
  "main": "./index.js",
  "exports": "./index.js"
} 

定义 "exports" 字段后，包的所有子路径都将被封禁，任何引入内部文件的声明都hi报错。为了引用内部文件，需要在 "exports" 字段上设置子路径导出[3]实现；而且，"exports" 还支持 条件导出[4]——为使用 require() 或 import() 的使用方分别指定要引入的文件，后续介绍。

子路径导出和条件导出其实为了弃用文件夹模块[5]功能而准备的。我们先来看看文件夹模块是怎么一回事。

文件夹模块

文件夹模块（Folders as modules）[6]其实是 Node.js 针对加载 CommonJS 文件所推出的一套查找算法。这套算法由于需要一些学习成本，还存在一定性能问题，因此 Node.js 团队在开始开发 ES Module 支持时，就准备弃用这套算法，改用通过扩展 "exports" 字段的方式，提供一套更加通用和简单的加载方式。

不过，由于多年积攒下来的庞大 CommonJS 代码库的存在，这套算法还会在很长一段时间内存在（虽然标记为 Legacy 了）。因此，学习这套文件夹模块的查找算法，对目前工作来说还是很有帮助的。

❝

注意：文件夹模块查找算法只对通过 require() 函数的加载生效，对通过 import() 的加载无效。

❞

Node.js 中，require() 支持以下 3 种情况下的文件夹加载：

一种情况，当前文件夹下存在一个 package.json 文件，并且还指定了 “main” 字段。

{ 
  "name" : "some-library",
  "main" : "./lib/some-library.js"
}

假设，我们现在就位于 some-library 目录下，那么 require('./some-library') 将会尝试加载 ./some-library/lib/some-library.js 文件。

如果当前目录下不存在 package.json 或者 "main" 未指定， 那么 require('./some-library') 将会尝试加载当前目录下的 index.js 或 index.node 文件。

  • ./some-library/index.js
  • ./some-library/index.node

如果上述 3 种尝试都失败了，Node.js 就报告错误了。

Error: Cannot find module 'some-library'

当然，针对在上述所有三种情况，import('./some-library') 都会导致出现 ERR_UNSUPPORTED_DIR_IMPORT 错误。

针对 node_modules 文件夹的特殊处理

node_modules 文件夹是一个特殊的文件夹，require() 会对它进行特殊处理。如果传递给 require() 的模块标识符不是核心模块，并且不以 '/'、'../' 或 './' 开头，那么 Node.js 就从当前模块的 node_modules 目录开始查找。如果找不到，就转移到父目录，依此类推，直到到达文件系统的根目录。

例如，我们在 '/home/ry/projects/foo.js'  文件中使用 require('bar.js')，则  Node.js 将按以下顺序查找文件：

  • /home/ry/projects/node_modules/bar.js
  • /home/ry/node_modules/bar.js
  • /home/node_modules/bar.js
  • /node_modules/bar.js

以上，就是在 Node.js 中 require() 加载文件夹上的策略了。

但 Node.js 是支持双模块系统的，为了得到 require() 和 import() 双重支持，我们需要使用包子路径导出和条件导出功能。

包的子路径导出

使用 "exports" 字段时，还有另外一种子路径（subpath exports）的写法。比如我们上面的写法：

{
  "exports": "./index.js"
} 

其子路径等价写法如下：

{
  "exports": {
    ".": "./index.js"
  }
} 

"." 指定的 key，称为主入口点（main entry point）。

当然，我们还可以定义其他路径，比如：

{
  "exports": {
    ".": "./index.js",
    "./submodule.js": "./src/submodule.js"
  }
} 

如此，使用方就可以以下 2 种方式导入我们的包：

import module from 'es-module-package';
import submodule from 'es-module-package/submodule.js';

就像我们之前说的，定义 "exports" 字段后，包的所有子路径都将被封禁，包括 package.json。

从 “main” 升级到 “exports”

当你将包从 "main" 升级到 "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"
  }
}

或者，项目可以选择使用导出模式（export patterns）[7]导出带有/不带有扩展子路径的整个文件夹：

{
  "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"
  }
}

这样， main、lib、feature目录下的所有文件都能引用了，不过并不推荐这种方式，还是要尽量减少对外入口的数量。

子路径导出模式

上面我们所提及的“导出模式”是一种类似于 glob pattern 的匹配算法。不过 pattern 中的 * 号不光匹配文件名，还匹配目录分隔符 /。

所以，下面的定义：

// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./features/*.js": "./src/features/*.js"
  }
} 

就能支持以下方式的导入：

// 加载单层目录中的文件
import featureX from 'es-module-package/features/x.js';
// Loads ./node_modules/es-module-package/src/features/x.js

// 加载嵌套目录中的文件
import featureY from 'es-module-package/features/y/y.js';
// Loads ./node_modules/es-module-package/src/features/y/y.js

包的条件导出

条件导出（conditional exports）提供了一种根据特定条件映射到不同路径的方法。这里的特定条件，既可以指引入方法（比如是通过 require() 导入还是 import 导入），还可以指执行环境（比如：node 还是其他（default））。

基于引入方法的导出

我们先从定义 require() 还是 import 方法的导出开始讲。例如，我们可以为 require() 和 import 提供不同的模块导出：

// package.json
{
  "exports": {
    "import": "./index-module.js",
    "require": "./index-require.cjs"
  },
  "type": "module"
}

"import" 字段定义使用 import 或 import() 方法引入的文件；"require" 字段则用来定义使用require() 加载时引入的文件。

基于环境的文件导出

当然，"exports" 字段还支持基于环境的文件导出判断。

// package.json
{
  "exports": {
    ".": "./index.js",
    "./feature.js": {
      "node": "./feature-node.js",
      "default": "./feature.js"
    }
  }
}

当前的这个包，在 Node.js 环境下，require('pkg/feature.js') 和 import 'pkg/feature.js' 加载的会是同一个 feature-node.js 文件；而在 Node.js 环境之外的其他 JS 环境下则会加载 feature.js 文件。

需要注意的时，使用环境判断时，请尽可能包含 "default" 条件——可以确保任何 Node.js 之外的 JS 环境都能有一个通用实现可以使用。

基于引入方法 & 环境的导出

当然，我们还能针对特定环境，为 "import" 和 "require()" 指定加载文件。

{
  "exports": {
    "node": {
      "import": "./feature-node.mjs",
      "require": "./feature-node.cjs"
    },
    "default": "./feature.mjs"
  }
}

以上，我们针对 Node.js 运行环境，分别对 require() 和 import 引入方式提供导出文件。

“imports”：另一种导出语法（仅限包内使用）

Node.js 还可以通过 "imports" 字段支持另外一种导出语法，不过仅限包内文件互相引用（以 # 号开头）。

如此定义：

// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./features/*.js": "./src/features/*.js"
  },
  "imports": {
    "#internal/*.js": "./src/internal/*.js"
  }
}

这样使用：

import featureX from 'es-module-package/features/x.js';
// Loads ./node_modules/es-module-package/src/features/x.js

import featureY from 'es-module-package/features/y/y.js';
// Loads ./node_modules/es-module-package/src/features/y/y.js

import internalZ from '#internal/z.js';
// Loads ./node_modules/es-module-package/src/internal/z.js

我们可以把 "imports" 字段看作是一种引用别名，有点类似于 tsconfig.json 中定义的 path，不过这是 Node.js 原生支持的。

在此不多赘述，有兴趣的同学，可以查看相关文档。

总结

本文首先介绍了 Node.js 中的模块系统。Node.js 里支持 CommonJS 和 ES Module 两种模块系统。有 2 种方法，可以判定一个文件使用的哪种模块语法：

  1. 通过文件后缀。.cjs 表示 CommonJS 模块文件，.mjs 表示 ES Module 模块文件
  2. 通过 package.json 文件的 "type" 字段。控制项目内 .js 文件使用的模块语法
    • 当值为 "module" 时，.js 文件表示 ES Module 文件
    • 当值为 "comonjs" 时（默认值，后续会改成 "module"），.js 文件表示 CommonJS 文件

针对第 2 种方式，Node.js 团队推荐始终声明 "type" 字段，指定 .js 所使用的模块语法。

然后，又介绍了如何定义一个 Node.js 包的导出。

Node.js 提供了 2 种导出方案："exports" 和 "imports"。前者对应外部导入，后者对应内部导入。我们着重讲解了 "exports"。

"exports" 替代了之前的 "main" 字段，而且还额外提供了子路径导出、条件导出能力来替代之前的文件夹模块方案。

总之，只要你使用的是最新的 Node v12、v14 版本，就可以放心使用以上介绍双模块系统、文件导出功能。

感谢你的阅读，Happy Coding！

参考资料

[1]

v14.17.0/v12.22.0 版本: https://nodejs.org/dist/latest-v20.x/docs/api/esm.html#modules-ecmascript-modules

[2]

v14.13.0/v12.20.0 版本: https://nodejs.org/dist/latest-v20.x/docs/api/packages.html#exports

[3]

子路径导出: https://nodejs.org/dist/latest-v20.x/docs/api/packages.html#subpath-exports

[4]

条件导出: https://nodejs.org/dist/latest-v20.x/docs/api/packages.html#conditional-exports

[5]

文件夹模块: https://nodejs.org/dist/latest-v20.x/docs/api/modules.html#folders-as-modules

[6]

文件夹模块（Folders as modules）: https://nodejs.org/dist/latest-v20.x/docs/api/modules.html#folders-as-modules

[7]

导出模式（export patterns）: https://nodejs.org/dist/latest-v20.x/docs/api/packages.html#subpath-patterns


原文始发于微信公众号（写代码的宝哥）：Node.js 包编写指南#1：模块系统与入口文件

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。

文章由极客之音整理，本文链接：https://www.bmabk.com/index.php/post/243663.html

赞 (0)
小半的头像小半
0 0

相关推荐

发表回复

登录后才能评论
极客之音——专业性很强的中文编程技术网站，欢迎收藏到浏览器，订阅我们！