Node.js v18.20.0 文档

基于模块的权限#

¥Module-based permissions

政策#

¥Policies

Node.js 包含了对创建加载代码的策略的实验性支持。

¥Node.js contains experimental support for creating policies on loading code.

策略是一个安全特性，旨在保证 Node.js 能够加载哪些代码。策略的使用假定策略文件的安全实践，例如确保 Node.js 应用不能使用文件权限覆盖策略文件。

¥Policies are a security feature intended to allow guarantees about what code Node.js is able to load. The use of policies assumes safe practices for the policy files such as ensuring that policy files cannot be overwritten by the Node.js application by using file permissions.

最佳实践是确保正在运行的 Node.js 应用的策略清单是只读的，并且正在运行的 Node.js 应用不能以任何方式更改该文件。一个典型的设置是将策略文件创建为与运行 Node.js 的用户 ID 不同的用户 ID，并向运行 Node.js 的用户 ID 授予读取权限。

¥A best practice would be to ensure that the policy manifest is read-only for the running Node.js application and that the file cannot be changed by the running Node.js application in any way. A typical setup would be to create the policy file as a different user id than the one running Node.js and granting read permissions to the user id running Node.js.

启用#

¥Enabling

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

¥The --experimental-policy flag can be used to enable features for policies when loading modules.

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

¥Once this has been set, all modules must conform to a policy manifest file passed to the flag:

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

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

¥The policy manifest will be used to enforce constraints on code loaded by Node.js.

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

¥To mitigate tampering with policy files on disk, an integrity for the policy file itself may be provided via --policy-integrity. This allows running node and asserting the policy file contents even if the file is changed on disk.

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

特性#

¥Features

错误行为#

¥Error behavior

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

¥When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities by defining an "onerror" field in a policy manifest. The following values are available to change the behavior:

• "exit"：将立即退出进程。不允许运行任何清理代码。

  ¥"exit": will exit the process immediately. No cleanup code will be allowed to run.

• "log"：将在发生故障的地方记录错误。

  ¥"log": will log the error at the site of the failure.

• "throw"：将在失败的地方抛出 JS 错误。这是默认值。

  ¥"throw": will throw a JS error at the site of the failure. This is the default.

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

完整性检查#

¥Integrity checks

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

¥Policy files must use integrity checks with Subresource Integrity strings compatible with the browser integrity attribute associated with absolute URLs.

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

¥When using require() or import all resources involved in loading are checked for integrity if a policy manifest has been specified. If a resource does not match the integrity listed in the manifest, an error will be thrown.

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

¥An example policy file that would allow loading a file checked.js:

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

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

¥Each resource listed in the policy manifest can be of one the following formats to determine its location:

1. 相对 URL 字符串 到清单中的资源，例如 ./resource.js、../resource.js 或 /resource.js。

   ¥A relative-URL string to a resource from the manifest such as ./resource.js, ../resource.js, or /resource.js.

2. 资源的完整 URL 字符串，例如 file:///resource.js。

   ¥A complete URL string to a resource such as file:///resource.js.

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

¥When loading resources the entire URL must match including search parameters and hash fragment. ./a.js?b will not be used when attempting to load ./a.js and vice versa.

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

¥To generate integrity strings, a script such as node -e 'process.stdout.write("sha256-");process.stdin.pipe(crypto.createHash("sha256").setEncoding("base64")).pipe(process.stdout)' < FILE can be used.

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

¥Integrity can be specified as the boolean value true to accept any body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid.

依赖重定向#

¥Dependency redirection

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

¥An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection can be used by intercepting attempts to load the modules wishing to be replaced.

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

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

¥The dependencies are keyed by the requested specifier string and have values of either true, null, a string pointing to a module to be resolved, or a conditions object.

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

¥The specifier string does not perform any searching and must match exactly what is provided to the require() or import except for a canonicalization step. Therefore, multiple specifiers may be needed in the policy if it uses multiple different strings to point to the same module (such as excluding the extension).

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

¥Specifier strings are canonicalized but not resolved prior to be used for matching in order to have some compatibility with import maps, for example if a resource file:///C:/app/server.js was given the following redirection from a policy located at 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') 之类的导入，则不会被拦截。

¥Any specifier used to load file:///C:/app/utils.js would then be intercepted and redirected to file:///C:/app/utils-v2.js instead regardless of using an absolute or relative specifier. However, if a specifier that is not an absolute or relative URL string is used, it would not be intercepted. So, if an import such as import('#utils') was used, it would not be intercepted.

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

¥If the value of the redirection is true, a "dependencies" field at the top of the policy file will be used. If that field at the top of the policy file is true the default node searching algorithms are used to find the module.

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

¥If the value of the redirection is a string, it is resolved relative to the manifest and then immediately used without searching.

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

¥Any specifier string for which resolution is attempted and that is not listed in the dependencies results in an error according to the policy.

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

¥Redirection does not prevent access to APIs through means such as direct access to require.cache or through module.constructor which allow access to loading modules. Policy redirection only affects specifiers to require() and import. Other means, such as to prevent undesired access to APIs through variables, are necessary to lock down that path of loading modules.

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

¥A boolean value of true for the dependencies map can be specified to allow a module to load any specifier without redirection. This can be useful for local development and may have some valid usage in production, but should be used only with care after auditing a module to ensure its behavior is valid.

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

¥Similar to "exports" in package.json, dependencies can also be specified to be objects containing conditions which branch how dependencies are loaded. In the preceding example, "http" is allowed when the "import" condition is part of loading it.

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

¥A value of null for the resolved value causes the resolution to fail. This can be used to ensure some kinds of dynamic access are explicitly prevented.

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

¥Unknown values for the resolved module location cause failures but are not guaranteed to be forward compatible.

示例：补丁依赖#

¥Example: Patched dependency

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

¥Redirected dependencies can provide attenuated or modified functionality as fits the application. For example, log data about timing of function durations by wrapping the original:

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

¥Use the "scopes" field of a manifest to set configuration for many resources at once. The "scopes" field works by matching resources by their segments. If a scope or resource includes "cascade": true, unknown specifiers will be searched for in their containing scope. The containing scope for cascading is found by recursively reducing the resource URL by removing segments for special schemes, keeping trailing "/" suffixes, and removing the query and hash fragment. This leads to the eventual reduction of the URL to its origin. If the URL is non-special the scope will be located by the URL's origin. If no scope is found for the origin or in the case of opaque origins, a protocol string can be used as a scope. If no scope is found for the URL's protocol, a final empty string "" scope will be used.

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

¥Note, blob: URLs adopt their origin from the path they contain, and so a scope of "blob:https://nodejs.cn" will have no effect since no URL can have an origin of blob:https://nodejs.cn; URLs starting with blob:https://nodejs.cn/ will use https://nodejs.cn for its origin and thus https: for its protocol scope. For opaque origin blob: URLs they will have blob: for their protocol scope since they do not adopt origins.

示例#

¥Example

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

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

¥Given a file located at file:///C:/app/bin/main.js, the following scopes would be checked in order:

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

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

¥This determines the policy for all file based resources within "file:///C:/app/bin/". This is not in the "scopes" field of the policy and would be skipped. Adding this scope to the policy would cause it to be used prior to the "file:///C:/app/" scope.

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

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

¥This determines the policy for all file based resources within "file:///C:/app/". This is in the "scopes" field of the policy and it would determine the policy for the resource at file:///C:/app/bin/main.js. If the scope has "cascade": true, any unsatisfied queries about the resource would delegate to the next relevant scope for file:///C:/app/bin/main.js, "file:".

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

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

¥This determines the policy for all file based resources within "file:///C:/". This is not in the "scopes" field of the policy and would be skipped. It would not be used for file:///C:/app/bin/main.js unless "file:///" is set to cascade or is not in the "scopes" of the policy.

4. "file:///"

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

¥This determines the policy for all file based resources on the localhost. This is not in the "scopes" field of the policy and would be skipped. It would not be used for file:///C:/app/bin/main.js unless "file:///" is set to cascade or is not in the "scopes" of the policy.

5. "file:"

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

¥This determines the policy for all file based resources. It would not be used for file:///C:/app/bin/main.js unless "file:///" is set to cascade or is not in the "scopes" of the policy.

6. ""

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

¥This determines the policy for all resources. It would not be used for file:///C:/app/bin/main.js unless "file:" is set to cascade.

使用范围的完整性#

¥Integrity using scopes

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

¥Setting an integrity to true on a scope will set the integrity for any resource not found in the manifest to true.

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

¥Setting an integrity to null on a scope will set the integrity for any resource not found in the manifest to fail matching.

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

¥Not including an integrity is the same as setting the integrity to null.

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

¥"cascade" for integrity checks will be ignored if "integrity" is explicitly set.

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

¥The following example allows loading any file:

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

使用范围的依赖重定向#

¥Dependency redirection using scopes

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

¥The following example, would allow access to fs for all resources within ./app/:

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

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

¥The following example, would allow access to fs for all data: resources:

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

示例：导入映射模拟#

¥Example: import maps emulation

给定导入映射：

¥Given an import map:

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

¥Import maps assume you can get any resource by default. This means "dependencies" at the top level of the policy should be set to true. Policies require this to be opt-in since it enables all resources of the application cross linkage which doesn't make sense for many scenarios. They also assume any given scope has access to any scope above its allowed dependencies; all scopes emulating import maps must set "cascade": true.

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

¥Import maps only have a single top level scope for their "imports". So for emulating "imports" use the "" scope. For emulating "scopes" use the "scopes" in a similar manner to how "scopes" works in import maps.

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

¥Caveats: Policies do not use string matching for various finding of scope. They do URL traversals. This means things like blob: and data: URLs might not be entirely interoperable between the two systems. For example import maps can partially match a data: or blob: URL by partitioning the URL on a / character, policies intentionally cannot. For blob: URLs import map scopes do not adopt the origin of the blob: URL.

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

¥Additionally, import maps only work on import so it may be desirable to add a "import" condition to all dependency mappings.