企业官网建设流程全解析

Insomnia 插件沙箱中 require 报 Module not permitted by manifest 怎么办

【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomnia

开发 Insomnia 的 template tag 插件时，如果你在 Preferences → Scripting 中打开了Run template tags in sandbox (experimental)，插件的run()就会在隔离的 QuickJS 沙箱内执行。此时对未授权的模块调用require('X')（例如require('fs')、require('events')或任意 npm 包），沙箱会抛出Module 'X' not permitted by manifest。解决办法是在插件自己的package.json中声明insomnia.permissions.modules，把该模块名加进授权清单，然后重新加载插件。

先确认错误属于哪一种

沙箱对require()采用默认拒绝（default-deny）模型，解析分两阶段（见 module-registry.ts）：

1. 模块名不在插件的授权集合内 → 抛Module 'X' not permitted by manifest；
2. 模块名已授权、但 Insomnia 的沙箱注册表里没有提供它 → 抛Module 'X' not available in sandbox。

这两种错误的处理方式完全不同，先分清再动手：

• not permitted by manifest：说明模块在沙箱注册表里存在，只是你的插件没声明。按本文方法在package.json加权限即可解决。
• not available in sandbox：说明你声明了一个 Insomnia 尚未打包进注册表的模块。这个错误不能靠改 manifest 解决，文档给出的路径是向 Insomnia 申请把它加入注册表（PERMISSIONS.md）。

哪些模块可以声明

沙箱注册表当前提供的模块（见 module-registry.ts 中的SANDBOX_MODULES）：

注意两点边界：

• uuid、ajv这类认证 npm 库由 Insomnia 独立打包，插件自带的node_modules永远不会被查询。沙箱里require('uuid')只会解析到 Insomnia 的注册表副本，插件无法用自己的同名实现替代它。
• 每个沙箱模块都是 Insomnia 提供的“认证安全等价实现”（纯 JS 重写或宿主 shim），不是原始 Node 内置模块。

在 package.json 中声明 permissions

报错的直接原因是 manifest 里没有该模块。修改插件的package.json，在insomnia字段下加入permissions.modules数组：

{ "name": "your-plugin", "version": "1.0.0", "main": "index.js", "insomnia": { "name": "your-plugin", "permissions": { "modules": ["events"], // require('events') 将被允许 "capabilities": [] // 仅 context.* 宿主能力需要；require 问题与它无关 } } }

上表中的模块名就是可写入modules数组的值（node:前缀别名在解析时会被规范化为规范名，例如node:events→events）。

如果你完全没有permissions块（即无 manifest 的插件），沙箱在拒绝非基线模块时会弹出一个一次性迁移通知，明确指出要补哪条授权。通知内容为（文档示例，来自 templating-worker-database.ts 中的 toast 文案）：

Plugin needs a permissions manifest"插件名" tried to require "模块名" but has no valid permissions manifest. Add insomnia.permissions.modules: ["模块名"] to its package.json to run it under the template-tag sandbox.

同一会话内，同一插件同一模块只提示一次；一个插件缺两个不同授权会分别提示。按提示把对应模块名加进insomnia.permissions.modules，然后重新加载插件即可。

另外注意 manifest 写法：modules必须是数组。形如"modules": "events"（非数组）的畸形声明不会生效，插件会降级到基线授权（只有path、crypto），并在 Preferences → Plugins 的插件卡片上显示警告——插件本身仍然加载。

验证修复是否生效

仓库自带一个手动测试插件 examples/insomnia-plugin-sandbox-demo，它的 package.json 声明了"modules": ["events", "uuid"]和"capabilities": ["storage"]，可直接用来对照验证。

验证步骤（来自 README.md）：

1. 在仓库根目录运行应用：npm run dev（开发模式）。
2. Preferences → Plugins →Reveal Plugins Folder，把insomnia-plugin-sandbox-demo文件夹复制进去。
3. 点击Reload Plugins（修改自己插件的 manifest 后同样要重新加载才生效）。
4. Preferences → Scripting → 打开Run template tags in sandbox (experimental)。
5. 在任意请求的 URL 或 header 中插入模板标签，例如{% eventsprobe %}，观察预览。

判断标准（均为文档给出的示例输出，不是固定预期）：

• 声明了events授权的插件：{% eventsprobe %}渲染events-ok；
• 未声明的插件执行同样代码：渲染Module 'events' not permitted by manifest；
• 基线模块无需声明：{% requireprobe 'path' %}渲染a/b；
• 越界模块仍然被拒绝：{% requireprobe 'fs' %}渲染Module 'fs' not permitted by manifest。

这些预期在冒烟测试 sandbox-template-tags.test.ts 中也被逐条断言，可作为行为核对依据。

最后到 Preferences → Plugins 展开你的插件详情，应能看到它声明的权限列表（如modules: events）；畸形 manifest 的插件会在卡片上带警告标记。

两个容易踩坑的写法问题

在run()里 require 认证库，而不是顶层。Insomnia 发现插件标签时是在宿主进程加载入口文件，而uuid/ajv只存在于沙箱注册表中。因此顶层require('uuid')在宿主侧就解析失败；必须放到标签的run()内，标签在沙箱执行时才能解析。相对路径的require('./util')不受此限制，顶层可用（多文件插件的相对 require 从插件目录内解析，只加载.js/.json文件，node_modules和点目录被跳过）。

别指望关闭沙箱来“绕过”。这个错误只出现在沙箱路径下；关闭沙箱开关后标签走旧的宿主进程路径。但权限 manifest 是沙箱路径的正式解决方式，文档未提供“禁用沙箱模块门控”的开关，不要依赖降级到非沙箱路径来规避。

边界说明

• 该错误只涉及 template tag 插件。Bundle（第一方）插件受信任，直接获得全部模块与能力，不会遇到此报错。
• credentials能力保留给第一方 bundle 插件，社区 template tag 插件即使声明也拿不到——它与require报错无关，但声明 manifest 时不要指望能加上它。
• 如果模块名已正确声明却报的是not available in sandbox而非not permitted，说明该模块尚不在注册表，manifest 无法解决，只能等 Insomnia 将其纳入注册表。

【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomnia