为什么 playground-elements 默认把沙箱放在 unpkg.com？读懂 4 条关键安全规则

为什么 playground-elements 默认把沙箱放在 unpkg.com？读懂 4 条关键安全规则

【免费下载链接】playground-elementsServerless coding environments for the web.项目地址: https://gitcode.com/gh_mirrors/pl/playground-elements

playground-elements 是一套运行在浏览器里的无后端代码沙箱编辑器（Serverless coding environments for the web），它默认把沙箱执行环境放在 unpkg.com 上。本文带你读懂这一设计背后的 4 条关键安全规则，让你安全地自定义sandboxBaseUrl而不踩坑。

先搞懂：Playground 的"沙箱"到底在做什么？

Playground 最大的特点是代码 100% 在浏览器里运行，不经过任何后端服务器。它的工作原理是：

1. 通过Service Worker拦截某个 URL 空间的请求，用你本地项目文件"伪造" HTTP 响应，相当于在浏览器里虚拟出一个网站；
2. 预览组件里的<iframe>指向这个虚拟 URL 的index.html，你在编辑器里改的代码就实时跑在这个 iframe 里。

也就是说，预览 iframe 里跑的任意 JavaScript，权限等同于该 URL 所在源（origin）的权限。如果 iframe 和你的站点同域，恶意代码就能通过window.parent篡改你的页面、读取你的 Cookie。这就是为什么"沙箱跑在哪个域名下"是 Playground 最核心的安全决策。

为什么默认选 unpkg.com？

在 src/playground-project.ts 中可以看到默认值：

sandboxBaseUrl = `https://unpkg.com/playground-elements@${npmVersion}/`

选 unpkg.com 有三个"恰好完美"的理由：

• 🔒天然无权限：unpkg.com 是一个公共 CDN，你的用户在这里没有任何登录态、Cookie 或敏感数据，恶意代码"偷无可偷"；
• 📦版本自动对齐：unpkg 按 npm 版本号托管包文件，沙箱所需的 Service Worker 文件与页面加载的组件永远同版本，不会因版本错配而出错（当前版本号由 src/shared/version.ts 自动生成）；
• 🌐默认跨站（cross-site）：对绝大多数站点来说，unpkg.com 与你处于不同顶级域，浏览器更容易为预览 iframe 分配独立进程，用户写死循环也不会卡死你的主页面。

另外注意：Playground 还默认用 unpkg.com 解析import 'lit'这类裸模块导入（除非你设置cdnBaseUrl），见 src/typescript-worker/worker-context.ts。

4 条关键安全规则：改沙箱地址前必读

官方文档明确警告：⚠️ 随意修改沙箱地址可能给你的站点引入安全漏洞。如果你要自定义sandbox-base-url，新地址必须同时满足以下 4 条规则（详见 README.md 的 "Sandbox security" 章节）：

规则 1：必须与宿主页「不同源」

沙箱源必须和承载 Playground 组件的页面源不同，否则不信任的代码可以通过window.parent直接篡改父窗口（比如把登录链接换成钓鱼地址）。官方还建议更进一步：使用完全不同的 site（不同顶级域），或通过Origin-Agent-Cluster响应头实现进程隔离。

规则 2：不能访问任何敏感 Cookie

沙箱源上不能存在用户的认证 Token、会话 Cookie 等。否则恶意代码可以把它们读走并转发到攻击者服务器。

规则 3：不能访问敏感资源与 API

无论是通过同源策略，还是通过你配置过的 CORS 头授予的跨域访问权，沙箱源都不能够调用change_password、get_credit_card之类的接口。简单说：这个源上不能挂任何"值钱"的接口。

规则 4：必须托管同版本的 2 个沙箱文件

新地址必须从 playground-elements 包中提供以下 2 个预压缩文件，且版本必须与你导入的组件完全一致：

• playground-service-worker.js
• playground-service-worker-proxy.html

Service Worker 负责"接管"虚拟 URL 空间的请求，而代理页面则负责在服务 Worker 重启后重新建立会话（其源码见 src/service-worker/playground-service-worker.ts）。版本不一致会导致文件协议不匹配，预览直接失效。

进阶：为什么浏览器会为沙箱开独立进程？

浏览器（如 Chrome）只为「不同 site」的 iframe 分配独立进程。origin 由协议+子域+顶级域+端口决定，而 site 只看协议+顶级域：example.com与foo.example.com是不同源但同站，example.com与example.net才是不同站。

如果沙箱与主站同站，可以在服务端对所有响应加Origin-Agent-Cluster: ?1头来强制进程隔离——Playground 的 Service Worker 返回项目文件时已经自动加了这个头（见 src/service-worker/playground-service-worker.ts），但你自己服务器上的其他响应也要加上。

什么时候才需要改掉默认的 unpkg.com？

只在两种场景下建议覆盖sandboxBaseUrl：

1. 不想依赖 unpkg.com 的可用性（它故障时预览会受影响）；
2. 内网环境无法访问公网 CDN。

替换时别忘了：如果不设sandboxBaseUrl，也要同时设置cdnBaseUrl（如https://cdn.jsdelivr.net/npm）来消除对 unpkg 的模块解析依赖，否则只堵住了一条路。这两个属性在 src/playground-ide.ts 和 src/playground-project.ts 中都可以通过 HTML 属性sandbox-base-url/cdn-base-url直接声明。

总结

默认值就是安全值。理解这 4 条规则后，无论是否自定义沙箱地址，你都能自信地向用户保证：Playground 里的任何代码都"跑不出笼子"。🛡️

【免费下载链接】playground-elementsServerless coding environments for the web.项目地址: https://gitcode.com/gh_mirrors/pl/playground-elements