Node.js v25.3.0 文档

基于进程的权限#>

【Process-based permissions】

权限模型#>

【Permission Model】

Node.js 权限模型是一种在执行期间限制访问特定资源的机制。API 位于标志 --permission 之后，当启用时，它将限制对所有可用权限的访问。

【The Node.js Permission Model is a mechanism for restricting access to specific resources during execution. The API exists behind a flag --permission which when enabled, will restrict access to all available permissions.】

可用的权限由 --permission 标志记录。

【The available permissions are documented by the --permission flag.】

在使用 --permission 启动 Node.js 时，通过 fs 模块访问文件系统、访问网络、生成进程、使用 node:worker_threads、使用原生插件、使用 WASI 以及启用运行时检查器的能力将受到限制（SIGUSR1 的监听器将不会被创建）。

【When starting Node.js with --permission, the ability to access the file system through the fs module, access the network, spawn processes, use node:worker_threads, use native addons, use WASI, and enable the runtime inspector will be restricted (the listener for SIGUSR1 won't be created).】

$ node --permission index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:23:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FileSystemRead',
  resource: '/home/user/index.js'
} 拷贝

允许访问以生成进程和创建工作线程可以分别使用 --allow-child-process 和 --allow-worker 来实现。

【Allowing access to spawning a process and creating worker threads can be done using the --allow-child-process and --allow-worker respectively.】

要允许网络访问，使用 --allow-net；在使用权限模型时允许本地插件，使用 --allow-addons 标志。对于 WASI，使用 --allow-wasi 标志。

【To allow network access, use --allow-net and for allowing native addons when using permission model, use the --allow-addons flag. For WASI, use the --allow-wasi flag.】

运行时 API#>

【Runtime API】

通过 --permission 标志启用权限模型时，会在 process 对象中添加一个新属性 permission。该属性包含一个函数：

【When enabling the Permission Model through the --permission flag a new property permission is added to the process object. This property contains one function:】

permission.has(scope[, reference])#>

在运行时检查权限的 API 调用 (permission.has())

【API call to check permissions at runtime (permission.has())】

process.permission.has('fs.write'); // true
process.permission.has('fs.write', '/home/rafaelgss/protected-folder'); // true

process.permission.has('fs.read'); // true
process.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false 拷贝

文件系统权限#>

【File System Permissions】

默认情况下，权限模型通过 node:fs 模块限制对文件系统的访问。它并不能保证用户无法通过其他方式访问文件系统，例如通过 node:sqlite 模块。

【The Permission Model, by default, restricts access to the file system through the node:fs module. It does not guarantee that users will not be able to access the file system through other means, such as through the node:sqlite module.】

要允许访问文件系统，请使用 --allow-fs-read 和 --allow-fs-write 标志：

【To allow access to the file system, use the --allow-fs-read and --allow-fs-write flags:】

$ node --permission --allow-fs-read=* --allow-fs-write=* index.js
Hello world! 拷贝

默认情况下，你的应用的入口点会被包含在允许读取的文件系统列表中。例如：

【By default the entrypoints of your application are included in the allowed file system read list. For example:】

$ node --permission index.js 拷贝

• index.js 将被包含在允许的文件系统读取列表中

$ node -r /path/to/custom-require.js --permission index.js. 拷贝

• /path/to/custom-require.js 将被包含在允许的文件系统读取列表中。
• index.js 将被包含在允许的文件系统读取列表中。

两个标志的有效参数是：

【The valid arguments for both flags are:】

• * - 分别允许所有 FileSystemRead 或 FileSystemWrite 操作。
• 相对于当前工作目录的路径。
• 绝对路径。

示例：

【Example:】

• --allow-fs-read=* - 它将允许所有 FileSystemRead 操作。
• --allow-fs-write=* - 它将允许所有 FileSystemWrite 操作。
• --allow-fs-write=/tmp/ - 它将允许对 /tmp/ 文件夹进行 FileSystemWrite 访问。
• --allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore - 它允许对 /tmp/ 文件夹 以及 /home/.gitignore 路径进行 FileSystemRead 访问。

也支持通配符：

【Wildcards are supported too:】

• --allow-fs-read=/home/test* 将允许读取与通配符匹配的所有内容。例如：/home/test/file1 或 /home/test2

在通配符字符（*）之后，所有后续字符将被忽略。例如：/home/*.js 的效果类似于 /home/*。

【After passing a wildcard character (*) all subsequent characters will be ignored. For example: /home/*.js will work similar to /home/*.】

当权限模型初始化时，如果指定的目录存在，它会自动添加通配符（*）。例如，如果 /home/test/files 存在，它将被视为 /home/test/files/*。然而，如果目录不存在，将不会添加通配符，并且访问将限制在 /home/test/files。如果你想允许访问尚不存在的文件夹，请确保明确包含通配符：/my-path/folder-do-not-exist/*。

【When the permission model is initialized, it will automatically add a wildcard (*) if the specified directory exists. For example, if /home/test/files exists, it will be treated as /home/test/files/*. However, if the directory does not exist, the wildcard will not be added, and access will be limited to /home/test/files. If you want to allow access to a folder that does not exist yet, make sure to explicitly include the wildcard: /my-path/folder-do-not-exist/*.】

在 npx 中使用权限模型#>

【Using the Permission Model with npx】

如果你正在使用 npx 来执行 Node.js 脚本，你可以通过传递 --node-options 标志来启用权限模型。例如：

【If you're using npx to execute a Node.js script, you can enable the Permission Model by passing the --node-options flag. For example:】

npx --node-options="--permission" package-name 拷贝

这会为 npx 启动的所有 Node.js 进程设置 NODE_OPTIONS 环境变量，而不会影响 npx 进程本身。

【This sets the NODE_OPTIONS environment variable for all Node.js processes spawned by npx, without affecting the npx process itself.】

使用 npx 时的文件系统读取错误

上述命令可能会抛出 FileSystemRead 无效访问错误，因为 Node.js 需要文件系统的读取权限来定位和执行该包。为避免此情况：

【The above command will likely throw a FileSystemRead invalid access error because Node.js requires file system read access to locate and execute the package. To avoid this:】

1. 使用全局安装的包 通过运行以下命令授予对全局 node_modules 目录的读取权限：

   npx --node-options="--permission --allow-fs-read=$(npm prefix -g)" package-name 拷贝

2. 使用 npx 缓存 如果你只是临时安装该包或依赖 npx 缓存， 请授予 npm 缓存目录的读取权限：

   npx --node-options="--permission --allow-fs-read=$(npm config get cache)" package-name 拷贝

你通常传递给 node 的任何参数（例如 --allow-* 标志）也可以通过 --node-options 标志传递。这种灵活性使在使用 npx 时根据需要配置权限变得非常容易。

【Any arguments you would normally pass to node (e.g., --allow-* flags) can also be passed through the --node-options flag. This flexibility makes it easy to configure permissions as needed when using npx.】

权限模型约束#>

【Permission Model constraints】

在使用此系统之前，你需要了解一些限制条件：

【There are constraints you need to know before using this system:】

• 该模型不会继承到工作线程。
• 使用权限模型时，以下功能将受限：
  • 原生模块
  • 网络
  • 子进程
  • 工作线程
  • 检查器协议
  • 文件系统访问
  • WASI
• 权限模型是在 Node.js 环境设置完成后初始化的。然而，某些标志，如 --env-file 或 --openssl-config，设计用来在环境初始化之前读取文件。因此，这些标志不受权限模型规则的约束。通过 v8.setFlagsFromString 在运行时设置的 V8 标志也是如此。
• 启用权限模型时，无法在运行时请求 OpenSSL 引擎，这会影响内置的 crypto、https 和 tls 模块。
• 当启用权限模型时，无法加载运行时可加载的扩展，这会影响 sqlite 模块。
• 通过 node:fs 模块使用现有的文件描述符会绕过权限模型。

限制和已知问题#>

【Limitations and Known Issues】

• 符号链接即使指向访问权限已授予路径集合之外的位置也会被跟随。相对符号链接可能允许访问任意文件和目录。在启用权限模型启动应用时，你必须确保已授予访问权限的路径中不包含相对符号链接。