Node.js v18.6.0 文档

启用#

中英对照

--experimental-policy 标志可用于在加载模块时启用策略特性。

一旦设置好，则所有模块都必须符合传给标志的策略清单文件：

node --experimental-policy=policy.json app.js

策略清单将用于对 Node.js 加载的代码实施约束。

为了减少对磁盘上策略文件的篡改，可以通过 --policy-integrity 提供策略文件本身的完整性。 这允许运行 node 并断言策略文件内容，即使文件在磁盘上被更改。

node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" app.js

特性#

错误的行为#

中英对照

当策略检查失败时，Node.js 默认会抛出错误。 通过在策略清单中定义 “onerror” 字段，可以将错误行为更改为几种可能性之一。 以下值可用于更改行为：

• "exit": 将立即退出进程。 不允许运行任何清理代码。
• "log": 将在发生故障的地方记录错误。
• "throw": 将在失败的地方抛出 JS 错误。 这是默认值。

{
  "onerror": "log",
  "resources": {
    "./app/checked.js": {
      "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"
    }
  }
}

完整性检查#

中英对照

策略文件必须使用与绝对 URL 关联的浏览器完整性属性兼容的子资源完整性字符串的完整性检查。

当使用 require() 或 import 时，如果已指定策略清单，则检查加载中涉及的所有资源的完整性。 如果资源与清单中列出的完整性不匹配，则会抛出错误。

允许加载文件 checked.js 的示例策略文件：

{
  "resources": {
    "./app/checked.js": {
      "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"
    }
  }
}

策略清单中列出的每个资源都可以采用以下格式之一来确定其位置：

1. 指向清单中资源的相对 URL 字符串，例如 ./resource.js、../resource.js 或 /resource.js。
2. 资源的完整 URL 字符串，例如 file:///resource.js。

当加载资源时，整个 URL 必须匹配，包括搜索参数和哈希片段。 尝试加载 ./a.js 时不会使用 ./a.js?b，反之亦然。

要生成完整性字符串，则可以使用 node -e 'process.stdout.write("sha256-");process.stdin.pipe(crypto.createHash("sha256").setEncoding("base64")).pipe(process.stdout)' < FILE 等脚本。

完整性可以指定为布尔值 true，以接受任何对本地开发有用的资源主体。 不建议在生产中这样做，因为它会允许资源的意外更改被认为是有效的。

依赖项重定向#

中英对照

应用程序可能需要发布模块的补丁版本或阻止模块允许所有模块访问所有其他模块。 可以通过拦截加载希望被替换的模块的尝试来使用重定向。

{
  "resources": {
    "./app/checked.js": {
      "dependencies": {
        "fs": true,
        "os": "./app/node_modules/alt-os",
        "http": { "import": true }
      }
    }
  }
}

依赖项由请求的说明符字符串作为键，并且具有 true、null、指向要解析的模块的字符串或条件对象的值。

说明符字符串不执行任何搜索，并且必须与提供给 require() 或 import 的内容完全匹配，但规范化步骤除外。 因此，如果策略使用多个不同的字符串指向同一个模块（例如排除扩展名），则可能需要多个说明符。

说明符字符串已规范化，但在用于匹配之前未解析，以便与导入映射具有某种兼容性，例如，如果资源 file:///C:/app/server.js 从位于 file:///C:/app/policy.json 的策略中获得以下重定向：

{
  "resources": {
    "file:///C:/app/utils.js": {
      "dependencies": {
        "./utils.js": "./utils-v2.js"
      }
    }
  }
}

任何用于加载 file:///C:/app/utils.js 的说明符将被拦截并重定向到 file:///C:/app/utils-v2.js，而不考虑使用绝对或相对说明符。 但是，如果使用的说明符不是绝对或相对 URL 字符串，则不会被截取。 所以，如果使用了 import('#utils') 之类的导入，则不会被拦截。

如果重定向的值为 true，将使用策略文件顶部的 "dependencies" 字段。 如果策略文件顶部的字段是 true，则使用默认节点搜索算法来查找模块。

如果重定向的值是字符串，则相对于清单进行解析，然后立即使用而无需搜索。

根据策略，任何尝试解析且未在依赖项中列出的说明符字符串都会导致错误。

重定向不会阻止通过直接访问 require.cache 或通过允许访问加载模块的 module.constructor 等方式访问 API。 策略重定向只影响到 require() 和 import 的说明符。 其他方法，例如防止通过变量对 API 的非期望访问，对于锁定加载模块的路径是必要的。

可以指定依赖项映射的布尔值 true 以允许模块加载任何说明符而无需重定向。 这对本地开发很有用，并且在生产中可能有一些有效的用途，但只有在审核模块以确保其行为有效后才应谨慎使用。

与 package.json 中的 "exports" 类似，依赖项也可以指定为包含条件的对象，这些条件分支如何加载依赖关系。 在前面的示例中，当 "import" 条件是加载它的一部分时，允许 "http"。

解析值的值 null 会导致解析失败。 这可用于确保明确阻止某些类型的动态访问。

已解析模块位置的未知值会导致失败，但不能保证向前兼容。

示例：修补依赖项#

中英对照

重定向的依赖可以提供适合应用程序的衰减或修改功能。 例如，通过封装原始记录有关函数持续时间的计时数据：

const original = require('fn');
module.exports = function fn(...args) {
  console.time();
  try {
    return new.target ?
      Reflect.construct(original, args) :
      Reflect.apply(original, this, args);
  } finally {
    console.timeEnd();
  }
};

作用域#

中英对照

使用清单的 "scopes" 字段一次设置多个资源的配置。 "scopes" 字段的工作原理是按片段匹配资源。 如果范围或资源包含 "cascade": true，则将在其包含范围内搜索未知说明符。 通过删除特殊方案的片段、保留尾随 "/" 后缀、以及删除查询和哈希片段来递归地减少资源 URL，可以找到级联的包含范围。 这导致 URL 最终减少到其来源。 如果 URL 是非特殊的，则范围将由 URL 的来源定位。 如果没有找到源的范围或在不透明源的情况下，可以使用协议字符串作为范围。 如果没有找到 URL 协议的范围，将使用最终的空字符串 "" 范围。

注意，blob: URL 采用它们包含的路径的来源，因此 "blob:https://nodejs.org" 的范围将无效，因为没有 URL 可以具有 blob:https://nodejs.org 的来源；以 blob:https://nodejs.org/ 开头的 URL 将使用 https://nodejs.org 作为其来源，因此 https: 作为其协议范围。 对于不透明的来源 blob: URL，它们的协议范围将具有 blob:，因为它们不采用来源。

示例#

中英对照

{
  "scopes": {
    "file:///C:/app/": {},
    "file:": {},
    "": {}
  }
}

给定一个位于 file:///C:/app/bin/main.js 的文件，将按顺序检查以下范围：

1. "file:///C:/app/bin/"

这决定了 "file:///C:/app/bin/" 中所有基于文件的资源的策略。 这不在策略的 "scopes" 字段中，将被跳过。 将此范围添加到策略将导致它在 "file:///C:/app/" 范围之前使用。

2. "file:///C:/app/"

这决定了 "file:///C:/app/" 中所有基于文件的资源的策略。 这是在策略的 "scopes" 字段中，它将确定 file:///C:/app/bin/main.js 资源的策略。 如果范围有 "cascade": true，则任何关于资源的不满意查询都将委托给 file:///C:/app/bin/main.js、"file:" 的下一个相关范围。

3. "file:///C:/"

这决定了 "file:///C:/" 中所有基于文件的资源的策略。 这不在策略的 "scopes" 字段中，将被跳过。 除非 "file:///" 设置为级联或不在策略的 "scopes" 中，否则它不会用于 file:///C:/app/bin/main.js。

4. "file:///"

这决定了 localhost 上所有基于文件的资源的策略。 这不在策略的 "scopes" 字段中，将被跳过。 除非 "file:///" 设置为级联或不在策略的 "scopes" 中，否则它不会用于 file:///C:/app/bin/main.js。

5. "file:"

这决定了所有基于文件的资源的策略。 除非 "file:///" 设置为级联或不在策略的 "scopes" 中，否则它不会用于 file:///C:/app/bin/main.js。

6. ""

这决定了所有资源的策略。 除非 "file:" 设置为级联，否则它不会用于 file:///C:/app/bin/main.js。

使用作用域的完整性检查#

中英对照

在范围上将完整性设置为 true 会将清单中未找到的任何资源的完整性设置为 true。

在范围上将完整性设置为 null 会将清单中未找到的任何资源的完整性设置为匹配失败。

不包括完整性与将完整性设置为 null 相同。

如果显式地设置了 "integrity"，则将忽略用于完整性检查的 "cascade"。

以下示例允许加载任何文件：

{
  "scopes": {
    "file:": {
      "integrity": true
    }
  }
}

使用作用域的依赖项重定向#

中英对照

以下示例将允许 ./app/ 内的所有资源访问 fs：

{
  "resources": {
    "./app/checked.js": {
      "cascade": true,
      "integrity": true
    }
  },
  "scopes": {
    "./app/": {
      "dependencies": {
        "fs": true
      }
    }
  }
}

以下示例将允许访问 fs 的所有 data: 资源：

{
  "resources": {
    "data:text/javascript,import('node:fs');": {
      "cascade": true,
      "integrity": true
    }
  },
  "scopes": {
    "data:": {
      "dependencies": {
        "fs": true
      }
    }
  }
}

示例：导入映射模拟#import maps

中英对照

给定导入映射：

{
  "imports": {
    "react": "./app/node_modules/react/index.js"
  },
  "scopes": {
    "./ssr/": {
      "react": "./app/node_modules/server-side-react/index.js"
    }
  }
}

{
  "dependencies": true,
  "scopes": {
    "": {
      "cascade": true,
      "dependencies": {
        "react": "./app/node_modules/react/index.js"
      }
    },
    "./ssr/": {
      "cascade": true,
      "dependencies": {
        "react": "./app/node_modules/server-side-react/index.js"
      }
    }
  }
}

导入映射假定您可以默认获取任何资源。 这意味着策略顶层的 "dependencies" 应设置为 true。 策略要求选择加入，因为它启用了应用程序交叉链接的所有资源，这对许多场景没有意义。 它们还假设任何给定的范围都可以访问超出其允许依赖项的任何范围；所有模拟导入映射的范围都必须设置 "cascade": true。

导入映射只有一个顶级作用域用于其 "imports"。 所以为了模拟 "imports" 使用 "" 范围。 为了模拟 "scopes"，使用 "scopes" 的方式与 "scopes" 在导入映射中的工作方式类似。

注意事项：策略不使用字符串匹配来寻找各种范围。 它们做 URL 遍历。 这意味着像 blob: 和 data: URL 之类的东西可能无法在两个系统之间完全互操作。 例如导入映射可以通过在 / 字符上对 URL 进行分区来部分匹配 data: 或 blob: URL，策略故意不能。 对于 blob: URL，导入映射范围不采用 blob: URL 的来源。

此外，导入映射仅适用于 import，因此可能需要向所有依赖项映射添加 "import" 条件。