@codesandbox/sandpack-client 变更日志深度解析:从 0.1.16 到 2.19.8 的核心能力演进与源码印证
@codesandbox/sandpack-client 变更日志深度解析:从 0.1.16 到 2.19.8 的核心能力演进与源码印证
@codesandbox/sandpack-client 是 Sandpack 组件工具集中与 CodeSandbox Bundler 交互的框架无关基础层,负责在宿主页面与 Bundler iframe 之间建立握手与消息通道。本文以 sandpack-client/CHANGELOG.md 为时间主线,逐版本梳理 runtime / node / static 三类客户端的能力演进、关键 Bug 修复与安全边界变化,并结合仓库源码与配置给出可直接落地的使用建议,帮助你理解该包每个历史版本背后实际解决了什么问题,以及今天应如何使用这些能力。
版本脉络:从 0.x 到 2.x 的三大阶段
CHANGELOG 完整记录了 @codesandbox/sandpack-client 从 2021 年 11 月的 0.1.16 到 2024 年 9 月的 2.19.8 的发布历史,当前仓库中 sandpack-client/package.json 声明的版本正是 2.19.8,与日志最新条目一致。整体演进可以划分为三个阶段:
- 0.x(2021-11 ~ 2022-05):核心能力奠基期,陆续加入 react-typescript 模板、SandpackTests、React DevTools、文件只读模式、沙箱 ID、loglevel 选项等;
- 1.x(2022-05 ~ 2023-02):
1.0.0引入破坏性变更(BREAKING CHANGES),重构 iframe 文件系统协议,引入自定义 npm registry、console 输出序列化、nodebox 支持、rollup 构建等; - 2.x(2023-02 ~ 2024-09):客户端类型体系成熟期,新增 static 模板、startRoute、任务管理器命令解析、Service Worker 能力、依赖下载进度、sandbox-id/团队 ID 等特性。
值得注意的是,日志中大量条目标注为 “Version bump only for package @codesandbox/sandpack-client”(如 2.4.3、2.3.1、0.17.0),说明本仓库使用 lerna monorepo 管理,这类条目只代表版本号联动发布,并不携带该包自身的功能变更——阅读时不应将它们误认为特性更新。
客户端架构:runtime、node 与 static 三足鼎立
CHANGELOG 中反复出现 client、node、static、sw、nodebox 等标签,对应的是 sandpack-client/src/clients 目录下的三类客户端实现。理解版本日志需要先建立这个架构背景:
| 客户端 | 源码入口 | 运行模型 | 典型模板 |
|---|---|---|---|
SandpackRuntime |
clients/runtime/index.ts | 通过 iframe 加载远程 Bundler,使用 IFrameProtocol 建立双向消息通道 |
react、vue、svelte、solid、angular 等前端模板 |
SandpackNode |
clients/node/index.ts | 基于 @codesandbox/nodebox 在浏览器内模拟 Node 运行时,用 shell 进程跑 dev server |
nextjs、astro、vite 等 Node 模板 |
SandpackStatic |
clients/static/index.ts | 使用 static-browser-server 直接预览静态 HTML 文件 |
static 模板 |
三类客户端都继承自 clients/base.ts 中的 SandpackClient 抽象基类,基类定义了统一的 sandboxSetup、options、status 状态机(initializing → installing-dependencies → transpiling → evaluating → idle → done)以及 updateSandbox / dispatch / listen / destroy 四个抽象方法。日志中 “node: add resize event”“Static Template: fix doctype injection” 等条目,正是这一多客户端架构下各自独立演进的证据。
关键能力演进逐一解读
1. Service Worker 支持(2.16 ~ 2.19)
日志中与 Service Worker 相关的条目最为密集,这是 2.x 后期最重要的方向之一:
2.18.0:Add support for enabling service worker feature;2.17.0:enable SW in the bundler;2.18.1:assign new channel port on reload;2.18.2:use stable sw id;2.19.8:generate new bundler id based on client version。
在源码中,该能力由 clients/runtime/index.ts 中 createBundlerURL、serviceWorkerHandshake 与 handleWorkerRequest 三个方法协同实现:
- 选项
experimental_enableServiceWorker开启后,Bundler URL 中的-{{suffix}}占位符会被替换为随机后缀(或experimental_stableServiceWorkerId指定的稳定 ID),从而为 Service Worker 生成独立的缓存作用域; - 开启后构造阶段即调用
serviceWorkerHandshake,通过MessageChannel与 iframe 内的 preview 建立专用通道,处理preview/request/preview/response消息——请求会先尝试从当前文件系统中查找文件,找不到时通过getTranspiledFiles向 Bundler 索要转译产物(这正是2.19.4修复 “sw: get transpiled files from bundler” 的落点); - 收到
refresh消息时会重新执行握手并重置 iframe 位置,避免页面 reload 后通道端口失效(对应2.18.1的修复)。
从 types.ts 的选项定义看,该能力目前仍标记为 experimental_ 前缀,experimental_stableServiceWorkerId 可用于让同一页面内多个实例共享同一 SW 缓存。2.19.8 的修复要点是:bundler id 现在基于客户端版本生成,避免版本升级后复用旧缓存导致行为不一致。
2. 自定义 npm registry(1.4.0)与私有依赖
1.4.0 引入 custom npm registries,配合 1.5.3(custom registry 只对 CodeSandbox URL 附带凭据)与 1.5.4(不为自定义 npm 请求设置默认凭据)的安全修复,构成了完整的私有包接入方案。选项定义位于 types.ts:
export interface NpmRegistry {
enabledScopes: string[]; // 哪些 scope 走该 registry,如 ["@myorg"]
limitToScopes: boolean; // 是否仅限这些 scope
registryUrl: string; // 私有 registry 地址
proxyEnabled: boolean; // 自托管需设为 false,否则会经由 CodeSandbox Proxy 转发
registryAuthToken?: string;// 认证令牌
}
仓库中 examples/custom-npm-registry 提供了完整可运行的本地私有 registry 示例(基于 htpasswd 做认证)。2.6.0 的 “private dep v2” 则是在此基础上的能力升级,配合团队 ID(teamId)让 Bundler 连接 CodeSandbox 解锁私有包能力。
3. 加载体验:进度、超时与 loading 状态
日志中关于加载与状态反馈的条目非常集中,说明这是社区反馈最密集的领域:
2.16.0:show dependency download progress——依赖下载进度可见化;2.16.1:update bundler to consume the correct loading message;2.0.24:increase preview timeout;2.0.25:throw error on timeout;2.6.4:disable loading state by default(runtime-client 默认关闭 loading 状态);2.1.0:Improved loading and restarts。
与加载状态相关的还有 ClientOptions 中的 showLoadingScreen(默认 false,见 runtime/index.ts)、showErrorScreen、showOpenInCodeSandbox 等布尔开关,以及 clearConsoleOnFirstCompile——Bundler 会在 iframe 首次编译时清空控制台。2.0.26 “preview: add stdout for long process” 则针对长时间运行的进程补充了 stdout 输出,避免用户误以为页面卡死。
4. 控制台与消息通道的演进
控制台能力经历了多次打磨:0.19.8 为 sandpack 消息增加 console 类型、0.19.9 修复 console message methods、2.0.15 将序列化后的控制台输出发送给父页面、2.7.0 为 static 模板接入 console hook、2.0.11 将 console-feed 移入 devDependencies。对应实现分布在 inject-scripts/consoleHook.ts(注入到预览 iframe 的 console 拦截脚本)与 SandpackConsole 组件链路中,支持的 console 方法类型定义在 types.ts(log/debug/info/warn/error/table/clear/time/timeEnd/count/assert)。
5. iframe 能力边界与安全(多项 Bug Fix)
iframe 的 sandbox 与 allow 属性在演进中持续扩权,源码 runtime/index.ts 与 static/index.ts 中保持一致:
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts allow-downloads allow-pointer-lock"
allow="accelerometer; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; clipboard-read; clipboard-write; xr-spatial-tracking;"
对应日志条目包括:
2.19.0:引入xr-spatial-tracking(WebXR 场景);2.14.3:允许 Clipboard API;2.11.1:为 iframe 增加allow-downloads。
这些变更直接决定了预览 iframe 中能运行哪些 Web API,若你的示例代码依赖 WebXR、剪贴板或下载功能,请务必确认使用的客户端版本不低于上述对应版本。
值得关注的代表性 Bug Fix 清单
以下是日志中较有代表性的修复条目,按主题归类:
| 主题 | 版本 | 修复内容 |
|---|---|---|
| 初始化并发 | 2.6.7 |
避免 compile 与 init 并发执行 |
| 模块删除 | 2.6.8 |
模块被移除时硬刷新页面 |
| 文件引用稳定性 | 2.0.17 |
让 files 引用更稳定 |
| 路径规范化 | 1.8.7 |
文件路径统一规范化 |
| 浏览器历史污染 | 0.14.8 |
防止在主页历史中新增路由 |
| 路由刷新 | 1.8.5 |
刷新时 iframe 保持正确 location |
| 环境变量 | 2.0.13 |
nodebox 命令支持环境变量 |
| 新文件感知 | 2.0.21 |
nodebox 识别 Sandpack 新增文件 |
| 递归写文件 | 2.0.23 |
nodebox writeFile 支持递归创建目录 |
| sandpackNode 初始化 | 2.13.7 |
修复 node 客户端初始化失败 |
| 编译选项合并 | 2.13.2 |
不覆盖 compile 默认属性 |
| 测试运行器复用 | 2.6.6 |
多次编译间复用同一 TestRunner |
| Solid 刷新 | 2.6.3 |
规避 solid refresh 的 bug |
| Angular 模板 | 2.19.7 |
postcss 转译 angular 模板 |
今日使用建议
基于上述演进,当前(2.19.8)接入 @codesandpack/sandpack-client 时的实用建议:
- 最小接入:参考 README.md 中的示例,通过
loadSandpackClient(selector, sandboxSetup, options?)加载客户端,files以/index.js这样的绝对路径为键,配合entry与dependencies完成一次编译:
import { loadSandpackClient } from "@codesandpack/sandpack-client";
const main = async () => {
const client = await loadSandpackClient("#preview", {
files: {
"/index.js": { code: `console.log(require('uuid'))` },
},
entry: "/index.js",
dependencies: { uuid: "latest" },
});
};
- 模板选择:前端模板走 runtime 客户端,Node 模板走 node 客户端,静态 HTML 走 static 客户端——包导出路径分别对应 package.json 中的
./clients/runtime、./clients/node、./clients/static三个子路径。 - 私有依赖:配置
customNpmRegistries时,自托管场景务必把proxyEnabled设为false,并仅在enabledScopes中声明需要走私有源的 scope。 - 调试手段:使用
logLevel(SandpackLogLevel枚举,见 types.ts,取值 None/Error/Warning/Info/Debug)控制 Bundler 日志量;startRoute可覆盖预览的初始路由。 - 升级注意:
1.0.0存在破坏性变更,从 0.x 升级时需要对照其迁移说明;Service Worker 相关选项仍带experimental_前缀,生产环境使用前应自行验证。
CHANGELOG 记录的每一次迭代,都能在 sandpack-client/src 的源码中找到对应实现或修复落点——这份日志既是发布记录,也是理解 Sandpack 客户端设计取舍的最佳索引。