企业官网建设流程全解析

Insomnia 如何搭建并运行模板标签沙箱探针插件验证 QuickJS 沙箱开关

【免费下载链接】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 中，设置项Run template tags in sandbox (experimental)（Preferences → Scripting）控制插件模板标签（template tag）的run()是在 Electron 主进程内直接执行，还是被路由进隔离的 QuickJS 沙箱。仓库自带一个手工测试用的探针插件 insomnia-plugin-sandbox-demo，通过它可以在界面上直观确认开关是否生效：把开关关掉和打开各渲染一次同一个标签，输出的ran in:字段会发生翻转，arch via bridge字段则证明异步 host bridge 能正常往返。

本文的任务就是：从源码运行 Insomnia，安装这个探针插件，插入探针标签，并在开关联动下核对渲染结果。

准备条件

根据根目录 package.json 的engines字段，本仓库要求：

• Node.js>=24.18.0
• npm>=11

在仓库根目录安装依赖（postinstall会执行patch-package、verify-bundle-plugins以及install-libcurl-electron，即安装 libcurl 的 Electron 预编译二进制，属于仓库声明的正常安装副作用）：

npm install

第一步：从源码启动应用

在仓库根目录运行：

npm run dev

该脚本对应npm start -w insomnia，会启动 Insomnia 开发版应用。

第二步：安装探针插件

按 examples/insomnia-plugin-sandbox-demo/README.md 的 Install (dev) 流程操作：

1. Preferences → Plugins → 点击Reveal Plugins Folder，打开插件目录；
2. 把仓库里的examples/insomnia-plugin-sandbox-demo文件夹完整复制进该目录（保持文件夹名不变）；
3. 点击Reload Plugins。

复制后不要改动插件内容，它的 package.json 声明了沙箱权限清单，后文的验证项依赖它：

{ "insomnia": { "name": "sandbox-demo", "permissions": { "modules": ["events", "uuid"], "capabilities": ["storage"] } } }

其中modules决定沙箱内require()可解析哪些模块，capabilities决定context.*可调用哪些 host 能力（详见 PERMISSIONS.md）。

第三步：开关关闭时的基线验证

1. 在任意请求的 URL 或 header 中插入插件提供的Sandbox Probe模板标签，或直接输入{% sandboxprobe 'hi' %}；
2. 打开该标签的编辑器查看 Live Preview。

开关关闭（默认状态）时，标签在主进程路径执行，输出形如（<arch>为当前系统架构，文档示例）：

hello | ran in: main-process | arch via bridge: <arch>

判断依据：沙箱路径会定义INSOMNIA_TEMPLATE_SANDBOX标记全局，主进程路径没有，index.js 中的探针就是靠它区分两条路径的：

const ranIn = typeof INSOMNIA_TEMPLATE_SANDBOX !== 'undefined' ? 'sandbox' : 'main-process';

注意不要再用process是否存在来区分——沙箱自 M2 起也提供process桩，它已不能作为判别信号。

第四步：打开 QuickJS 沙箱开关并验证

1. Preferences → Scripting → 打开Run template tags in sandbox (experimental)；
2. 回到同一个标签，确认 Live Preview 输出变为（文档示例）：

hello | ran in: sandbox | arch via bridge: <arch>

ran in: sandbox说明标签的run()已被路由进 QuickJS 沙箱；arch via bridge: <arch>说明context.util.nodeOS()经__hostBridge→pluginToMainAPI['nodeOS']的异步往返正常工作（探针代码见 index.js）。

一个需要注意的现象：开关是读到主进程侧设置的，若刚切换开关后预览还是旧值，重新打开标签编辑器再渲染一次即可。自动化测试套件 sandbox-template-tags.test.ts 中assertTagPreviewEventually就是反复重开标签轮询直到输出反映新开关，以此处理这个传播时延。

可选：用同一插件的其余探针核对清单与能力边界

该插件还带了若干探针标签，都服务于同一个验证目标（沙箱开关生效后的各条权限路径）：

未声明events的插件会收到Module 'events' not permitted by manifest；未声明storage的插件会收到Capability 'storage' not granted — add it to insomnia.permissions.capabilities。

限制与已知边界

以下限制来自 PERMISSIONS.md 与探针 README，验证时如遇到对应现象属于预期行为而非故障：

• 沙箱内require('X')解析到的永远是 Insomnia 自带的"审核过的安全等价实现"（纯 JS 重实现或 host 支持的 shim），不是原始 Node 内建模块；uuid、ajv等经审核的 npm 库由 Insomnia 预打包并锁定版本。
• 插件自带的node_modules从不被沙箱读取；裸require('uuid')永远解析到注册表中的审核副本。
• 经审核库的require必须写在标签的run()内部，不要写在顶层——插件发现阶段仍在宿主进程加载入口文件，顶层require('uuid')/require('ajv')会解析失败。
• credentials能力保留给第一方捆绑插件，社区模板标签插件即使声明也不会被授予。
• permissions块格式错误（如modules不是数组）会降级为基线授权并在 Preferences → Plugins 的插件卡片上给出警告，插件仍会加载。
• 未声明permissions的旧插件触及非基线模块时，会收到一次性迁移提示，指明要添加的授权项。
• 该开关标注 experimental，属于实验性设置。

如果不想手工在界面上核对，也可以直接跑仓库的 Playwright 冒烟测试 sandbox-template-tags.test.ts：它写入一个同构探针插件、导入 sandbox-probe-collection.yaml 夹具、切换toggle-plugin-sandbox开关，并对ran in:翻转、基线/未授权模块、标准库一致性逐项断言。

验证完成的标准可以收敛为一句：同一标签在开关关闭时输出ran in: main-process，打开后输出ran in: sandbox，且两种状态下arch via bridge都给出真实架构值而不是bridge-error——这就是 QuickJS 沙箱开关端到端生效的证据。

【免费下载链接】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