Builder.io Qwik SDK 版本演进指南从 0.2 到 0.25 的核心能力、破坏性变更与实战配置【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io Qwik SDKbuilder.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.16API 成熟期完成 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 apiVersionv2 /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-vm0.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参数自定义 isolate0.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.0isolated-vm从 5.0.0 升级到 6.0.0以支持 Node v24破坏性变更不再支持 Node 18 与 20。核心数据获取 API 的演进0.10 ~ 0.25API 重命名从 Render 系列到 fetch 系列0.14.0 是一次集中的破坏性版本移除了以下旧导出旧导出新导出RenderBlocksBlocksRenderContentContentgetContentfetchOneEntrygetAllContentfetchEntries同时Content的includeRefsprop 与fetchOneEntry的includeRefs/noTraverse参数被移除统一由enrich取代废弃的副作用式registerComponent()被移除改由Content的customComponentsprop 承担注册职责。0.10.0 还规定fetchAllEntries/getAllContent直接返回内容数组而非包一层{ results }对象。fetch 错误语义不再静默返回 null0.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.tsexport 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默认 0userAttributes用于个性化定向的用户属性键值对如{ urlPath: /, returnVisitor: true, device: mobile }queryMongoDB 风格查询如query: { data.myCustomField: { $gt: 20 } }0.14.21 修复了 query 扁平化问题fields/omit字段白名单 / 黑名单omit优先级更高0.18.10 修正了omit默认值为meta.componentsUsedlocale自动解析本地化字段0.16.24 起标准化 locale 处理cacheSeconds/staleCacheSecondsCDN 缓存控制sort如{ createdDate: 1 }includeUnpublished是否包含草稿内容fetch/fetchOptions0.14.10 加入0.14.15 修正类型自定义 fetch 及请求选项apiHost0.16.19 加入默认https://cdn.builder.iocanTrack为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 与核心 props0.18.0 起model与content成为Content的必填 props。围绕它演进出的核心 props 包括apiHost内容获取 API 端点默认https://cdn.builder.iotrustedHosts0.12.2决定 SDK 在哪些 host 下开启编辑/预览模式并收紧默认 host 校验nonce0.16.1为 SDK 内联的style/script标签设置nonce属性CSP 场景customComponents注册自定义组件的推荐方式替代被移除的registerComponent()副作用linkComponent0.12.4自定义链接组件应用于 Button 组件链接、任意块的 Link URL 字段、Columns 块的 Link 字段isPreviewing相关0.14.4 起isPreviewing/isEditing支持接收search参数URLSearchParams | string | object便于 SSR 环境判断当前请求是否为预览/编辑请求0.14.16 修复了服务端isPreviewing逻辑包裹组件 props0.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.90.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是否为合法 URL0.25.6使用精确的可信主机名校验 Visual Editor 消息来源拒绝格式错误或非 HTTP(S) 的 origin0.7.1视觉编辑逻辑改为通过自定义事件触发而非OnMount从而移除了全部水合逻辑视觉编辑相关修复0.16 ~ 0.180.16.21修复 preview 模式下的构建0.16.22修复编辑器内空块的可视化编辑0.17.2修复 Builder Visual Editor Studio 标签页中的内容预览0.18.1修复 Content Editor 中更新输入值不触发 iframe 变化的问题0.18.4Custom Code 块的代码更新在视觉编辑中实时反映0.18.12Symbol 条目在 Visual Editor 中变化时正确加载对应内容个性化、A/B 测试与用户属性A/B 测试的 SSR 支持与去重0.4.0A/B 测试在 SSR 时正确渲染且向后兼容0.4.3isHydrationTarget环境判断更准确0.4.5页面内容中嵌套的 Symbol 支持 SSR A/B 测试0.7.4多重 SSR A/B 测试逻辑修复内联 A/B 脚本在构建期字符串化避免运行时字符串化导致的不一致个性化容器与用户属性 cookie0.18.14支持 Variant Container 与块级个性化block level personalization0.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 bindings0.5.0在非 Node.jsedge、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.00.15.0 新增shouldReceiveBuilderProps配置默认让自定义组件接收builderBlock与builderContextshouldReceiveBuilderProps: { 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.15onChange回调新增第二个参数previousOptions变更前的 options 状态并支持 async 函数0.17.10.16.6 / 0.16.3序列化注册组件中的函数如showIf字段函数、注册组件信息中的全部函数0.25.11类型上允许showIf回调通过context.locale接收当前编辑器 locale0.17.3补充自定义组件 Input 的folded、keysHelperText类型BuilderContent增加firstPublished0.23.2恢复 inputs 的description支持内置块Blocks组件演进图像与视频块0.19.0 / 0.19.1RawImg 组件支持srcsetVideo 组件使用 IntersectionObserver 懒加载RawImg 增加loadinglazy0.25.8暴露 Image 的sizes字段修复 Gen 2 SDK 中响应式源选择0.14.27 / 0.14.29Image 块支持highPriority急切加载与webp上传格式0.17.1扩展 Image / Video 块允许的文件类型0.14.6Image 块在未提供altText时设置rolepresentation0.18.8Image 增加title选项0.16.2SVG 图片移除冗余srcset0.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 块补keypropTabs 块0.14.18移植自 gen1 widgetsSlot 块0.12.1、Animations 支持0.12.7、hover 动画0.14.160.14.31TextArea 块支持0.22.1Raw: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.0isolated-vm升级到 6.0.0支持 Node v24弃用 Node 18/200.14.19Node 运行时复用同一 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: v3v2 不可用0.14.0RenderContent→Content、RenderBlocks→Blocks、getContent→fetchOneEntry、getAllContent→fetchEntriesincludeRefs/noTraverse全部改为enrich移除副作用式registerComponent()改用customComponentsprop0.16.0shouldReceiveBuilderProps默认值全部改为false自定义组件默认不再接收 Builder props0.17.0fetchEntries/fetchOneEntry对错误与非成功响应改为抛出异常0.18.0subscribeToEditor改为具名参数对象且apiKey必填Content的model与content变为必填 props0.16.0Columns列宽按 gutter 比例扣除的算法修正0.23.0Node 18 / 20 不再受支持0.10.0fetchAllEntries/getAllContent直接返回数组而非{ results }对象相关资源SDK 使用入口与安装说明README多环境打包与子路径导出package.json取数 API 完整选项类型get-content/types.tsfetchOneEntry/fetchEntries实现与错误语义get-content/index.tsNode 运行时初始化isolated-vmnode-runtime/init.tsSDK 公共导出清单server-index.ts、index.ts内置块与组件源码Image、Video、Form、Columns、Accordion、Tabs 等packages/sdks/src/blocks【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考