Node.js模块处理方式

February 10, 2024

Node.js

本文不讨论具体的模块解析和识别方式，见文档

CommonJS modules

require() 模块解析算法

CommonJS 模块执行前会被如下函数包装：（参见此处 Node.js 源码）

(function (
    exports: Module["exports"], // 指向 module.exports
    require: Require,
    module: Module, // 指向当前模块
    __filename: string,
    __dirname: string,
) {
    // 对 module.exports *同步*赋值，将值导出
    // module.exports 默认值是一个空对象，exports 仅当包装模块时是对这个对象的引用
    // 最终实际导出值是 module.exports，而不是 exports
});

为了验证之，测试 arguments 变量即可

// test.cjs
console.log(arguments);

require() 函数定义如下

interface Require {
    (id: string): any;
    resolve: RequireResolve;
    cache: Dict<NodeModule>;
    main: Module | undefined;
}

interface RequireResolve {
    (id: string, options?: { paths?: string[] | undefined }): string;
    paths(request: string): string[] | null;
}

interface Module {
    isPreloading: boolean;
    exports: any;
    require: Require;
    id: string;
    filename: string;
    loaded: boolean;
    children: Module[];
    path: string;
    paths: string[];
}

require() 函数对于相同输入 id，仅导入（执行）一次（在第一次时缓存，缓存到 require.cache 对象中），重复导入将得到相同的引用（在缓存 require.cache 中读取）。
注意 cjs 导入的结果是普通的 JavaScript 值，即导出和导入得到的值是相同的。（esm 则有不同）
此外 Node.js 内置模块都是可写的对象，这就允许它们被替换。而由于导入的是相同的引用，因此修改是立即可见的。

对于内置模块，如果不带 node: 前缀，也会尝试从 require.cache 中读取。
但若加上 node: 前缀则不会。因此 node: 前缀将保证能够获取到内置模块，但注意内置模块本身还是允许被修改的。

require("fs").write = (fd, str, cb) => {
    console.log(str + " <patched>");
};

require.cache.fs = {
    exports: {
        write() {
            console.log("fake!");
        },
    },
};

require.cache["node:fs"] = {
    exports: {
        write() {
            console.log("fake!");
        },
    },
};

// 确保得到内置模块，但内置模块本身允许被修改
const fs1 = require("node:fs");
fs1.write(1, "Hi, fs1", (err) => {}); // => Hi, fs1 <patched>

// 会先从缓存中读取
const fs2 = require("fs");
fs2.write(1, "Hi, fs2", (err) => {}); // => fake!

删除 require.cache 的键就可以令对应 id 重新加载导入

ECMAScript modules

esm 模块除了遵循语言规范外，还有 Node.js 的模块解析算法
 mlly 库可能会有帮助

require() 导入的值与对应 module.exports 导出的值完全相同。
但在 ECMAScript 标准模块中，当导入整个模块作为一个对象时，得到是一个 Module 对象。
该对象是普通的 JavaScript 对象，但其原型为 null，其 Symbol.toStringTag 键对应值为字符串 Module。
export 导出的对应键，在该对象中都是不可写的。

import * as m from "./esm.js";
const m = await import("./esm.js");

Object.getPrototypeOf(m) // => null

// m 相当于如下
{
    [Symbol.toStringTag]: 'Module'
    // ... 包含其它 export 导出的对应键
}

Node.js 模块的 esm 导出，是命名导出所有 API，并将 CommonJS 导出值以 default 导出。
这种方式导出方式就很方便了，因为：

// 无需（当然也可以）
import * as fs from "fs";
// 只需（因为有 default 导出）
import fs from "fs";

以第一种导入方式时，根据 esm 规范，该对象的键当然是不可写的。
第二种方式导入的相当于 require() 返回值，因此其键可写。

default 导出值就是 CommonJS 导出值。因此只有修改 default 导出值，才能在 esm 环境中修改内置模块，
但需调用特殊的 syncBuiltinESMExports 函数，才能传播修改。

import fs, { readFileSync } from "node:fs";
import { syncBuiltinESMExports } from "node:module";
import { Buffer } from "node:buffer";

fs.readFileSync = () => Buffer.from("Hello, ESM");
syncBuiltinESMExports();

fs.readFileSync === readFileSync; // => true

对于我们自己编写的 cjs 模块，根据文档：
esm 环境导入 cjs 模块时，module.exports 对象提供为 default 导出。为了更好的兼容性，会静态分析来提供命名导出。

esm 环境没有 require 函数，通过以下方法得到：

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);

Typescript

moduleResolution 选项

module 选项决定编译器输出的模块类型，moduleResolution 决定如何解析输入的模块。

对于现代 Node.js 应用，使用 tsc 编译时，指定为 nodenext 即可。此时会仿照 Node.js 模块解析方式。
对于浏览器环境，往往真正是由其它 bundler 来解析依赖，因此指定为 bundler。此时允许省略文件名后缀。

allowSyntheticDefaultImports 和 esModuleInterop 选项

typescript 本身是根据 declaration 来识别导出的，这就可能导致 default 导入出现问题。

这些选项可处理此问题，具体参见handbook和对应文档。

bundler

esm 规范中，import 不能省略文件名后缀（毕竟浏览器是网络请求，而不是本地文件系统），但很多 bundler 在解析 import 时并不会这么严格。

rollup

@rollup/plugin-commonjs 包 extensions 选项

webpack

resolve.extensions

esbuild

resolve extensions

←Back to home

This work is licensed under CC BY-NC-SA 4.0