Node.js 插件沙箱：开放扩展之前先限制能力

Node.js 插件沙箱：开放扩展之前先限制能力

一、插件系统会放大风险

开源工具做到一定阶段，用户会希望写插件：自定义命令、接入模型、改输出格式、增加发布目标。插件系统能让生态变活，但也会把未知代码引入运行环境。Node.js 插件如果没有沙箱，风险很高。

插件可能读取本地文件、访问网络、执行命令、泄露环境变量。开放扩展之前，先限制能力，而不是等出事后再补权限。

二、插件能力要声明

flowchart TD A[插件安装] --> B[读取 manifest] B --> C[能力声明] C --> D[用户确认] D --> E[沙箱执行]

插件 manifest 应声明需要的能力，例如读取工作区文件、写输出目录、访问网络、调用模型接口。工具运行时按声明授予能力。

默认不应该给插件完整 Node.js 权限。很多插件只需要处理字符串或生成文件，不需要访问整个系统。

三、API 要通过宿主转发

type PluginContext = { readFile(path: string): Promise<string> writeFile(path: string, content: string): Promise<void> fetch(url: string): Promise<Response> log(message: string): void }

插件不直接拿fs和process.env，而是通过宿主提供的 API。宿主可以做路径限制、敏感信息过滤和审计。

{ "name": "markdown-exporter", "permissions": ["read:workspace", "write:dist"] }

权限越具体，用户越容易判断是否合理。

四、执行要可观测和可中断

插件执行时间、文件访问、网络请求都应记录。长时间运行的插件要能被取消，异常要隔离，不能拖垮宿主工具。

还要考虑版本兼容。插件 API 变化时，需要语义化版本和废弃周期。否则生态刚起来，就会因为宿主升级而大面积失效。

沙箱实现可以分阶段。第一阶段用受控上下文和权限 API 限制能力；第二阶段再考虑 Worker、独立进程或 WebAssembly。不要一开始就承诺绝对安全，但要清楚说明当前安全边界。

plugin_runtime: timeout_ms: 5000 max_output_kb: 512 allow_child_process: false allow_env_access: false

插件市场还要有审核和签名机制。用户安装插件时，应看到作者、版本、权限变更和校验信息。插件升级如果新增权限，必须重新提示用户确认。

错误隔离同样重要。一个插件抛异常，不应该让整个工具崩溃。宿主应捕获错误、标记插件失败，并提供禁用入口。扩展生态越开放，隔离越重要。

插件还要有最小测试套件。插件作者提交时，至少要证明插件能加载、权限声明合法、核心命令能执行、错误时不会让宿主退出。宿主可以提供脚手架生成这些测试。

plugin_test_contract: manifest_valid: true loads_in_sandbox: true handles_error: true declares_permissions: true

对于企业用户，可以提供锁定插件版本和私有插件源。这样既能享受扩展能力，又不会被公共插件市场的变化影响生产环境。

沙箱不是一次性功能，而是一组长期治理能力：权限、审核、隔离、升级和撤销都要一起设计。

五、总结

Node.js 插件沙箱要通过 manifest 声明能力，由宿主提供受控 API，并记录执行行为。

插件系统的目标是扩展能力，不是把工具变成无限权限的脚本执行器。