Builder.io Qwik SDK 版本演进指南：从 0.2 到 0.25 的核心能力、破坏性变更与实战配置-育师

Builder.io Qwik SDK 版本演进指南：从 0.2 到 0.25 的核心能力、破坏性变更与实战配置

【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder

Builder.io Qwik SDK（@builder.io/sdk-qwik）是 Builder.io 可视化开发平台面向 Qwik 框架的官方 SDK，由 Mitosis 生成，用于在 Qwik 应用中渲染可视化内容、实现 A/B 测试与个性化、以及和 Builder Visual Editor 深度集成。本指南以该 SDK 的 CHANGELOG 为骨架，逐版本梳理从0.2到0.25.13的关键能力演进、破坏性变更、数据绑定求值原理与多运行时打包策略，帮助你在升级或集成时准确对照版本行为。

版本速览与整体脉络

@builder.io/sdk-qwik当前版本为0.25.13（见 package.json）。其版本演进大体可划分为三个阶段：

0.2 ~ 0.7（能力奠基期）：确立apiVersion: v3默认值、引入 SSR A/B 测试、enrichAPI 标志、isolated-vm沙箱、多环境打包（browser / node / edge）以及 changesets 发布流程。
0.8 ~ 0.16（API 成熟期）：完成 API 重命名（RenderContent→Content、getContent→fetchOneEntry等）、enrich取代includeRefs、shouldReceiveBuilderProps精细化、initializeNodeRuntime节点运行时初始化、以及大量块（Block）组件与交互修复。
0.17 ~ 0.25（个性化与稳定性期）：fetchEntries/fetchOneEntry改为错误抛出、setClientUserAttributes个性化 cookie 工具、Variant Container支持、内联脚本去重、enrichOptions引用富化约束等。

起步与运行时打包策略（0.2 ~ 0.7）

默认 API 版本 v3 与`apiVersion`覆盖

0.2.0 起，SDK 将默认apiVersion设置为v3。0.13.0 更进一步：移除v2作为合法apiVersion，仅允许v3。在较老版本中，如需回退可显式指定：

<RenderContent apiVersion="v2" />

getContent({ apiVersion: "v2" });

从源码类型定义看，当前版本GetContentOptions.apiVersion的类型已被收窄为'v3'（见 types.ts），即 v2 不再可用。

多环境 Bundle 与子路径导出

0.6.0 将构建管线升级为按运行时生成三套独立产物：browser、node、edge。0.14.3 将子路径导出迁移为/bundle/edge、/bundle/node、/bundle/browser。当前 package.json 的exports字段即为这套策略的落地：

node/electron→lib/node/index.qwik.*
browser/default→lib/browser/index.qwik.*
edge-routine、workerd、deno、lagon、netlify、edge-light、bun→lib/edge/index.qwik.*
另有./node/init专用入口，对应 Node 运行时初始化模块

Node 运行时：`initializeNodeRuntime`与`isolated-vm`

0.7.1 起 SDK 引入isolated-vm，在 Node 环境中将动态数据绑定代码放入沙箱 VM 执行。0.16.7 增加@builder.io/sdk-qwik/node/init入口，导出initializeNodeRuntime。该函数必须放在仅服务端的位置调用，例如 Qwik 的entry.ssr.tsx：

// entry.ssr.tsx import { renderToStream, type RenderToStreamOptions, } from "@builder.io/qwik/server"; import { manifest } from "@qwik-client-manifest"; import Root from "./root"; import { initializeNodeRuntime } from "@builder.io/sdk-qwik/node/init"; initializeNodeRuntime(); export default function (opts: RenderToStreamOptions) { return renderToStream(<Root />, { manifest, ...opts, }); }

源码 init.ts 说明了为何需要单独文件导入：isolated-vm只能从绝不运行在客户端的文件中导入，且必须独立存放，否则会混入 SDK 主入口导致浏览器端报错。initializeNodeRuntime内部通过setIvm将 IVM 实例存入全局变量，并支持ivmIsolateOptions参数自定义 isolate（0.14.19 引入，用于复用同一 Isolate 实例并显著提升长任务性能）。

版本相关注意点：

0.12.5：修复 Node v20 + M1 Mac 上的 sigfault 崩溃，在该环境跳过isolated-vm。
0.14.19：所有数据绑定复用同一个 Isolate 实例，提升 Node 运行时性能。
0.16.13：从浏览器与 edge bundle 移除 node-runtime 逻辑，并禁用 arm64 + Node 20 上的initializeNodeRuntime。
0.23.0：isolated-vm从 5.0.0 升级到 6.0.0，以支持 Node v24；破坏性变更：不再支持 Node 18 与 20。

核心数据获取 API 的演进（0.10 ~ 0.25）

API 重命名：从 Render 系列到 fetch 系列

0.14.0 是一次集中的破坏性版本，移除了以下旧导出：

旧导出	新导出
`RenderBlocks`	`Blocks`
`RenderContent`	`Content`
`getContent`	`fetchOneEntry`
`getAllContent`	`fetchEntries`

同时，Content的includeRefsprop 与fetchOneEntry的includeRefs/noTraverse参数被移除，统一由enrich取代；废弃的副作用式registerComponent()被移除，改由Content的customComponentsprop 承担注册职责。0.10.0 还规定fetchAllEntries/getAllContent直接返回内容数组，而非包一层{ results }对象。

fetch 错误语义：不再静默返回 null

0.17.0 起，fetchEntries与fetchOneEntry会将fetch抛出的任何错误、或 Builder API 返回的非成功响应直接抛出，而非像之前那样吞掉错误返回null。这要求调用方增加 try/catch 或错误边界处理。对应实现见 get-content/index.ts：当响应不含results时记录错误并throw content。

`fetchOneEntry`的`enrichOptions`与引用富化

0.25.13 为fetchOneEntry和Content新增enrichOptions，用于约束引用富化（reference enrichment）的深度与字段范围，同时将约束信息告知 Visual Editor。GetContentOptions中对应的类型定义（见 types.ts）：

export interface EnrichOptions { /** * How many levels of nested references to resolve. Higher levels multiply * response size, so prefer the lowest level your content needs. */ enrichLevel?: number; /** * Per-model field filters applied to resolved references. */ model?: { [modelName: string]: { /** Comma-separated list of fields to include */ fields?: string; /** Comma-separated list of fields to omit */ omit?: string; }; }; }

enrichOptions仅在enrich: true时生效；enrichLevel越高，响应体越大，建议取内容所需的最低层级。与之配套的常用取数参数还包括：

model（必填）、apiKey（必填）
limit（默认 1）、offset（默认 0）
userAttributes：用于个性化定向的用户属性键值对，如{ urlPath: '/', returnVisitor: true, device: 'mobile' }
query：MongoDB 风格查询，如query: { 'data.myCustomField': { $gt: 20 } }（0.14.21 修复了 query 扁平化问题）
fields/omit：字段白名单 / 黑名单，omit优先级更高；0.18.10 修正了omit默认值为meta.componentsUsed
locale：自动解析本地化字段（0.16.24 起标准化 locale 处理）
cacheSeconds/staleCacheSeconds：CDN 缓存控制
sort：如{ createdDate: 1 }
includeUnpublished：是否包含草稿内容
fetch/fetchOptions（0.14.10 加入，0.14.15 修正类型）：自定义 fetch 及请求选项
apiHost（0.16.19 加入，默认https://cdn.builder.io）
canTrack：为false时禁用 cookie 定向与 A/B 测试（0.14.26 修复了 Symbols 中不生效的问题）

SDK 还会自动为 API 请求附加 SDK 标识头（0.16.18），并在process.env.DEBUG === 'true'时打印每次 API URL 命中日志（0.16.23）。

Content 组件的 props 与渲染行为

必填 props 与核心 props

0.18.0 起model与content成为<Content>的必填 props。围绕它演进出的核心 props 包括：

apiHost：内容获取 API 端点，默认https://cdn.builder.io
trustedHosts（0.12.2）：决定 SDK 在哪些 host 下开启编辑/预览模式，并收紧默认 host 校验
nonce（0.16.1）：为 SDK 内联的style/script标签设置nonce属性（CSP 场景）
customComponents：注册自定义组件的推荐方式（替代被移除的registerComponent()副作用）
linkComponent（0.12.4）：自定义链接组件，应用于 Button 组件链接、任意块的 "Link URL" 字段、Columns 块的 "Link" 字段
isPreviewing相关：0.14.4 起isPreviewing/isEditing支持接收search参数（URLSearchParams | string | object），便于 SSR 环境判断当前请求是否为预览/编辑请求；0.14.16 修复了服务端isPreviewing逻辑

包裹组件 props

0.9.0 引入contentWrapper、contentWrapperProps、blocksWrapper、blocksWrapperProps四类 props，分别控制内容容器与块列表容器的元素类型与附加 props，默认均为div。0.18.13 扩展了BlocksWrapperProps语义：<Blocks />可接收BlocksWrapperProps覆盖<Content />设置的全局 props，且局部 props 完全替换全局 props（除非手动合并）：

// 全局 props，作用于所有 <Blocks /> <Content blocksWrapperProps={{ style: { padding: 10 } }} /> // 覆盖全局 props（背景色生效，padding 失效） <Blocks BlocksWrapperProps={{ style: { backgroundColor: 'red' } }} /> // 手动合并全局与局部 props（背景色与 padding 同时生效） <Blocks BlocksWrapperProps={{ ...builderContext.BlocksWrapperProps, style: { backgroundColor: 'red' } }} />

内联脚本的去重与按需注入（0.25.5 / 0.25.9）

0.25.5 修复了多 Content 组件页面中重复注入 A/B 测试内联脚本的问题：window.builderIoAbTest/window.builderIoRenderContent初始化脚本只在 Content 真正渲染 A/B 变体时输出一次，且定义为幂等并在水合目标上自清理，避免此前通过客户端 DOM 变更导致的注水回归。0.25.9 将同样策略推广到个性化脚本：window.builderIoPersonalization/window.filterWithCustomTargeting/window.updateVisibilityStylesScript仅在块中确实包含 Variant Container 时注入，且定义幂等。0.25.2 / 0.25.3 曾尝试直接去重 DOM 中的重复 A/B 脚本，后因回归被回退，最终以按需注入方案解决。

编辑器集成与安全

subscribeToEditor 的命名参数重构（0.18.0 破坏性变更）

0.18.0 将subscribeToEditor的参数改为具名参数对象，且apiKey变为必填：

// 旧写法（已失效） subscribeToEditor('page', () => { ... }, { trustedHosts: ['...'] }) // 新写法 subscribeToEditor({ apiKey: '...', model: '...', trustedHosts: ['...'], callback: () => { ... } })

该函数（0.12.8 加入）用于监听内容变更，适合预览数据模型等场景。

消息来源校验

SDK 与 Visual Editor 的通信基于postMessage，因此消息来源校验一直是安全重点：

0.14.28：先检查e.origin是否为合法 URL
0.25.6：使用精确的可信主机名校验 Visual Editor 消息来源，拒绝格式错误或非 HTTP(S) 的 origin
0.7.1：视觉编辑逻辑改为通过自定义事件触发，而非OnMount，从而移除了全部水合逻辑

视觉编辑相关修复（0.16 ~ 0.18）

0.16.21：修复 preview 模式下的构建
0.16.22：修复编辑器内空块的可视化编辑
0.17.2：修复 Builder Visual Editor Studio 标签页中的内容预览
0.18.1：修复 Content Editor 中更新输入值不触发 iframe 变化的问题
0.18.4：Custom Code 块的代码更新在视觉编辑中实时反映
0.18.12：Symbol 条目在 Visual Editor 中变化时正确加载对应内容

个性化、A/B 测试与用户属性

A/B 测试的 SSR 支持与去重

0.4.0：A/B 测试在 SSR 时正确渲染，且向后兼容
0.4.3：isHydrationTarget环境判断更准确
0.4.5：页面内容中嵌套的 Symbol 支持 SSR A/B 测试
0.7.4：多重 SSR A/B 测试逻辑修复；内联 A/B 脚本在构建期字符串化，避免运行时字符串化导致的不一致

个性化容器与用户属性 cookie

0.18.14：支持 Variant Container 与块级个性化（block level personalization）
0.17.7：导出setClientUserAttributes辅助函数，用于设置/更新 Builder 的用户属性 cookie，该 cookie 被 Personalization Containers 用于决定渲染哪个变体：

import { setClientUserAttributes } from "@builder.io/sdk-qwik"; setClientUserAttributes({ device: "tablet", });

0.25.12：修复 Builder Studio 定向请求中布尔型用户属性（boolean user attributes）的处理

数据绑定求值的运行时优化

SDK 在 browser / node / edge 三种运行时执行动态绑定（data bindings）：

0.5.0：在非 Node.js（edge、serverless 等）服务端运行时支持基础数据绑定
0.14.7：为动态绑定求值器增加缓存层，并修复嵌套组件的 state 响应性
0.16.14：在 Content 初始化时（而非 "on mount"）执行 JS 代码与 HTTP 请求；改进 edge 运行时解释器对 async/await polyfill（典型如jsCode块）的处理，以及 state 值 getter/setter 的处理
0.16.16：优化简单的state.*读访问绑定——避免运行时 eval，直接从 state 取值
0.2.1 / 0.2.2：支持用户 JS 代码块中的响应式 state 值、动态 Link URL 绑定

组件系统：自定义组件、Props 传递与类型

shouldReceiveBuilderProps 的默认值变更（0.15.0 / 0.16.0）

0.15.0 新增shouldReceiveBuilderProps配置，默认让自定义组件接收builderBlock与builderContext：

shouldReceiveBuilderProps: { builderBlock: true, builderContext: true, builderComponents: false, builderLinkComponent: false, }

0.16.0 是破坏性变更：默认值改为全部关闭，SDK 默认不再向自定义组件传递任何 Builder props，除非显式开启：

shouldReceiveBuilderProps: { builderBlock: false, // 原为 true builderContext: false, // 原为 true builderComponents: false, builderLinkComponent: false, }

需要特定 Builder props 时，按需覆盖：

export const componentInfo = { name: "Text", shouldReceiveBuilderProps: { builderBlock: true, builderContext: false, builderComponents: true, builderLinkComponent: false, }, inputs: [ { name: "text", type: "html", required: true, autoFocus: true, bubble: true, defaultValue: "Enter some text...", }, ], };

0.14.27 与此呼应：仅在需要时向块与自定义组件传递 Builder props，减少不必要的 props 传递。

组件注册与类型增强

0.17.2：导出RegisteredComponents与BuilderContextInterface类型；将 Text 块的内联绑定（如Hello {{state.name}}）求值移出组件，便于自定义 Text 块实现复用
0.25.10：组件元数据类型新增可选group?: string，可将自定义组件归入编辑器插入菜单的自定义手风琴分组，且不产生 excess-property 类型错误；Image 组件在 alt 文本为空时渲染显式空alt属性
0.16.15：onChange回调新增第二个参数previousOptions（变更前的 options 状态），并支持 async 函数（0.17.1）
0.16.6 / 0.16.3：序列化注册组件中的函数（如showIf字段函数）、注册组件信息中的全部函数
0.25.11：类型上允许showIf回调通过context.locale接收当前编辑器 locale
0.17.3：补充自定义组件 Input 的folded、keysHelperText类型，BuilderContent增加firstPublished
0.23.2：恢复 inputs 的description支持

内置块（Blocks）组件演进

图像与视频块

0.19.0 / 0.19.1：RawImg 组件支持srcset，Video 组件使用 IntersectionObserver 懒加载，RawImg 增加loading="lazy"
0.25.8：暴露 Image 的sizes字段，修复 Gen 2 SDK 中响应式源选择
0.14.27 / 0.14.29：Image 块支持highPriority（急切加载）与webp上传格式
0.17.1：扩展 Image / Video 块允许的文件类型
0.14.6：Image 块在未提供altText时设置role="presentation"
0.18.8：Image 增加title选项
0.16.2：SVG 图片移除冗余srcset；0.17.6：移除 Video 块导致子元素被隐藏的 z-index

表单相关块

0.13.2 加入 Form、FormSelect、FormSubmit、FormInput 块；0.14.31 补充 TextArea 与 Select 块的required选项；0.18.15 修复表单提交错误处理；0.14.23 修复 Qwik SDK 表单事件提交；0.20.1 修复表单提交应使用 radio 按钮的值而非 name。

布局与交互块

Columns 块：0.16.0 破坏性变更——按比例扣除 gutter 空间计算百分比宽度（此前平均扣除导致高space时明显错误）；0.18.9 修复固定高度下列内元素居中；0.16.20 修复列状态对 props 的响应性
Accordion 块（0.14.22 引入）：0.16.22 修复条目顺序与空块可视化编辑；0.17.3 为循环内 Accordion 块补keyprop
Tabs 块（0.14.18，移植自 gen1 widgets）
Slot 块（0.12.1）、Animations 支持（0.12.7）、hover 动画（0.14.16）
0.14.31：TextArea 块支持
0.22.1：Raw:Img 组件信息增加额外 inputs 字段

跟踪与分析

0.24.1：修复trackConversion方法
0.18.2：修复/track重复曝光调用，以及默认/变体场景下的重复/track调用校验
0.4.4：跟踪 URL 从builder.io/api/v1/track迁移到cdn.builder.io/api/v1/track以提高可靠性
0.3.1：向 Visual Editor 发送的数据中附带 SDK 版本，便于调试

性能与稳定性专项

0.24.0：消除长运行 Node.js 进程中的内存泄漏
0.23.0：isolated-vm升级到 6.0.0（支持 Node v24，弃用 Node 18/20）
0.14.19：Node 运行时复用同一 Isolate 实例提升性能
0.16.13：从 browser / edge bundle 剔除 node-runtime 逻辑
0.5.5：移除lru-cache依赖；0.5.4：移除多余acorn导入修复构建问题
0.14.1：将isolated-vm的 dynamicRequire 移出全局作用域，减少崩溃
0.14.7：动态绑定求值器增加缓存层

升级建议与破坏性变更清单

综合 CHANGELOG，升级时需重点关注的破坏性变更（按影响面排序）：

0.13.0 / 0.2.0：仅允许apiVersion: 'v3'，v2 不可用
0.14.0：RenderContent→Content、RenderBlocks→Blocks、getContent→fetchOneEntry、getAllContent→fetchEntries；includeRefs/noTraverse全部改为enrich；移除副作用式registerComponent()，改用customComponentsprop
0.16.0：shouldReceiveBuilderProps默认值全部改为false，自定义组件默认不再接收 Builder props
0.17.0：fetchEntries/fetchOneEntry对错误与非成功响应改为抛出异常
0.18.0：subscribeToEditor改为具名参数对象且apiKey必填；<Content>的model与content变为必填 props
0.16.0（Columns）：列宽按 gutter 比例扣除的算法修正
0.23.0：Node 18 / 20 不再受支持
0.10.0：fetchAllEntries/getAllContent直接返回数组而非{ results }对象

Builder.io Qwik SDK 版本演进指南：从 0.2 到 0.25 的核心能力、破坏性变更与实战配置