@codesandbox/sandpack-client 变更日志深度解析:从 0.1.16 到 2.19.8 的核心能力演进与源码印证

原创2026-10-09 23:44:421,961 阅读
文章标签:前端开发工具UI组件

@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 时的实用建议:

  1. 最小接入:参考 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" },
  });
};
  1. 模板选择:前端模板走 runtime 客户端,Node 模板走 node 客户端,静态 HTML 走 static 客户端——包导出路径分别对应 package.json 中的 ./clients/runtime、./clients/node、./clients/static 三个子路径。
  2. 私有依赖:配置 customNpmRegistries 时,自托管场景务必把 proxyEnabled 设为 false,并仅在 enabledScopes 中声明需要走私有源的 scope。
  3. 调试手段:使用 logLevel(SandpackLogLevel 枚举,见 types.ts,取值 None/Error/Warning/Info/Debug)控制 Bundler 日志量;startRoute 可覆盖预览的初始路由。
  4. 升级注意:1.0.0 存在破坏性变更,从 0.x 升级时需要对照其迁移说明;Service Worker 相关选项仍带 experimental_ 前缀,生产环境使用前应自行验证。

CHANGELOG 记录的每一次迭代,都能在 sandpack-client/src 的源码中找到对应实现或修复落点——这份日志既是发布记录,也是理解 Sandpack 客户端设计取舍的最佳索引。

登录后查看全文
sandpack