Node.js 26 --permission 稳定后仍不是沙箱：权限模型能挡住什么、挡不住什么

把 Node.js 服务升级到 26 之后，团队常会顺手打开 --permission：既然 Permission Model 已经正式稳定，是不是就能直接把它当成轻量沙箱用？答案是不能。它很适合给脚本和线上服务收紧文件读写、子进程、Worker 这类运行时能力，但防护边界始终停留在 Node.js 进程内部，完全替代不了容器隔离、操作系统权限管控或者网络访问策略。

--permission 的核心价值是缩小 Node.js 代码“默认什么操作都能做”的权限范围；它的定位从来不是把不可信代码直接丢进去就能保安全的沙箱。生产环境落地时，要把运行时权限、进程身份、容器规则和网络出口限制凑在一起做纵深防护。

“稳定”到底稳定了什么

Node.js 20 首次上线 Permission Model 的时候，对应的开关还是 --experimental-permission。到 Node.js 24 的发布说明里，入口就改成了 --permission；现在 Node.js 26 的官方文档直接把它列为稳定能力。这里说的“稳定”，核心指的是对外暴露的 API 和运行逻辑已经进入可长期依赖的阶段，不等于它的安全等级突然就追上了常规沙箱。

可以先拿一个极简脚本直观感受下它的边界：

import { readFileSync } from 'node:fs';

console.log(readFileSync('./config/app.json', 'utf8'));

不带特殊参数直接跑的时候，它能读取当前进程身份可访问的所有文件。加上 --permission 之后，所有没明确授予的权限默认全部收紧；如果配置文件所在的目录没有被列入读取白名单，调用直接就会失败，还会带上 ERR_ACCESS_DENIED 的标识。这也是它最实用的设计：把以前很容易漏的“事后补限制”逻辑，直接改成了“所有权限必须主动声明才能开放”。

权限检查发生在哪一层

我们把一次读取配置文件的完整链路拆解开，判断就会清晰很多：启动参数先定义好全局的权限策略，Node.js 内置 API 在对应调用点做权限校验，操作系统最后还是会按进程的所属用户、文件本身的权限规则再做一轮校验。三层里任意一层不允许，这次读取操作就没法完成。

举个例子，下面的启动命令只给指定的配置目录开放读取权限：

node --permission \
  --allow-fs-read=./config \
  app.mjs

这么配置不等于“应用的配置访问就绝对安全了”。如果第三方依赖包还需要读取证书目录、临时目录或者运行时生成的缓存目录，服务启动之后还是会在对应路径上报错。更稳妥的做法是先完整记录进程真实的所有访问动作，再把涉及的目录按用途分组授予权限，别为了服务能立刻跑起来直接放开整个文件系统的访问权限。

一样的思路也适用于 --allow-child-process、Worker、WASI 和原生扩展这些能力：每一项权限都要和实际业务动作对应上，别图省事直接把所有开关一次性全部打开。

最容易误判的三个场景

把它当成操作系统级沙箱

Permission Model 只负责管控 Node.js 运行时内部能不能调用指定能力，没法帮你自动设置 UID、目录所有者、系统调用白名单或者容器网络规则。进程本身还是运行在宿主机或者容器分配的身份之下，运维层面的错误授权不会被 Node.js 的启动参数自动修正。

只测试主入口逻辑，不校验依赖路径

主程序可能只需要读取 config 路径，但日志库、证书加载器、构建类工具很可能会访问其他目录。测试的时候要覆盖启动流程、健康检查、定时任务和异常恢复全链路，尤其要留意动态导入、子进程派生、Worker 初始化这类容易被忽略的场景。

看到 audit 模式就以为操作已经被阻断

官方文档明确区分了 enforce 和 audit 两种模式：前者直接拒绝没有权限的操作，后者只会执行权限检查、通过诊断通道推送违规事件，本身不会真的阻断访问。审计模式适合刚迁移时用来盘点全量访问点，绝对不能被误当成上线之后的防护规则。上线前一定要确认当前进程实际运行的是哪一种模式。

从 Node.js 22 迁移时先看这张清单

Node.js 官方的迁移说明里已经提示过从 22 升级到 24 时要检查平台差异和行为变化；如果继续升级到 26，权限策略也应该作为固定的启动契约保存下来。你可以按下面的顺序逐步排查：

1. 完整列出来进程实际需要的文件读取、文件写入、子进程、Worker、WASI 和原生扩展能力。
2. 先在测试环境用审计模式收集全所有访问点，再把已经确认稳定的路径改成明确的允许范围。
3. 把对应的启动参数写入正式部署配置，还要单独对健康检查、定时任务、回滚命令做一轮权限验证。
4. 在容器层面继续限制进程用户、文件夹挂载规则和网络出口范围，别把 Node.js 权限参数当成唯一的安全边界。

遇到 ERR_ACCESS_DENIED 报错的时候，先确认是哪个 API 触发、对应哪个路径、缺失哪一项允许参数，再判断要不要小幅扩大权限范围。临时把所有权限全部放开虽然能快速恢复服务，但这么做完全失去了迁移权限模型的意义。

相关问题

Node.js Permission Model 能限制网络访问吗？

它的核心能力定位不是通用网络防火墙。网络出口、域名访问和连接目标的管控，应该交给容器规则、主机防火墙或者云网络策略来处理，再配合应用自身的请求合法性校验做多层防护。

打开 --permission 之后第三方依赖包会全部失效吗？

不会全部失效，但依赖包里的隐式文件访问、子进程派生、Worker 创建或者原生扩展调用逻辑很可能被直接拒绝。你可以先在测试环境跑完整条业务链路，再逐项授予最小范围的对应权限。

生产环境应该直接启用吗？

如果当前服务的访问边界本身就很清晰，可以把它作为纵深防御的其中一层直接启用；如果还没有盘点完所有依赖的访问路径，可以先开审计模式，配合集成测试收集全量访问点之后再切到强制模式，避免把上线后出现的权限报错误判成参数本身的故障。

结语

Node.js 26 自带的 Permission Model 完全值得深入落地，它直接把 Node.js 运行时的权限逻辑从过去的默认继承改成了显式声明配置。但“稳定”解决的只是接口可用性和行为成熟度问题，不会自动帮你完成整套隔离设计。把它和最小进程身份配置、只读挂载规则、容器网络策略以及依赖审计放在同一份部署核对清单里，才是这项能力适合接入生产环境的正确姿势。