@builder.io/sdk 核心 SDK 演进全解析：从内容获取 API 到视觉编辑安全与类型体系的版本脉络

builder.io/sdk 核心 SDK 演进全解析从内容获取 API 到视觉编辑安全与类型体系的版本脉络【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本指南以packages/core/CHANGELOG.md为主线系统梳理builder.io/sdkBuilder 核心 SDK即 builder/builder 仓库中的 packages/core 包从 v1.1.26 到 v6.3.3 的演进历程。它聚焦三大主线内容获取 API 的形态变迁apiVersion / apiEndpoint / enrich 富化体系、视觉编辑器与宿主页面之间的安全模型强化以及自定义组件注册类型体系的完善。读者将掌握builder.get/builder.getAll的完整参数语义、enrichOptions的深度控制、trusted host 校验机制以及升级到 6.x 时需要注意的破坏性变更。一、SDK 定位与仓库全景builder.io/sdk是 Builder 视觉开发平台在浏览器与服务端共用的核心运行时仓库根目录的 README.md 将其定位为Content API 的封装。包内package.json见 packages/core/package.json当前版本为 6.3.3提供浏览器版dist/index.browser.js、CommonJSdist/index.cjs.js、ESMdist/index.esm.js与类型声明dist/index.d.ts四种产物直接依赖仅hash-sum、node-fetch与tslib是一个轻量的零框架核心。SDK 的核心能力都集中在 builder.class.ts 的单例Builder类上初始化builder.init(YOUR_KEY)、内容获取get/getAll/getContent、用户属性定位setUserAttributes、自定义组件注册registerComponent、事件跟踪track/trackConversion/trackImpression以及与视觉编辑器的 postMessage 通信。仓库内其余框架 SDKReact、Vue、Svelte、Qwik 等均在此基础上构建因此这份 CHANGELOG 实际上也是整个 Builder SDK 生态的底层演进史。二、内容获取 API 的形态变迁apiVersion 与 apiEndpoint 的两条演进线CHANGELOG 中最清晰的一条主线是内容从哪里取的反复调整它直接影响所有调用builder.get/builder.getAll的应用。2.1 apiVersionv1 与 v3 的默认值摇摆v1.1.35 首次引入apiVersion属性允许在v1与v3之间切换默认v1v1.2.0 将默认值改为v3v1.3.0 又改回v1直到 v2.0.0 最终确定默认v3并沿用至今。这一摇摆最终收敛为常量DEFAULT_API_VERSION v3定义在 packages/core/src/types/api-version.ts。在 flushGetContentQueue 中可以看到运行时校验apiVersion必须是v1或v3否则抛出Invalid apiVersion错误——对应的单元测试位于 builder.class.test.ts。2.2 apiEndpointquery 端点与 content 端点的取舍这是 CHANGELOG 中破坏性变更最密集的一条线值得单独梳理时间线版本变更内容v3.0.3给builder.get()/builder.getAll()增加apiEndpoint参数可选content/query默认queryv4.0.0移除apiEndpoint参数Content API 成为唯一端点后因 Symbol 渲染缺陷回退v5.0.0回归使用/query端点修复 v4.0.0 引入的 Symbol 渲染问题v6.0.0将apiEndpoint提升为builder实例级属性content/query再次移除get/getAll及BuilderContent组件上的参数官方注释明确指出旧参数并未按预期工作v6.0.0 之后apiEndpoint作为实例属性由BehaviorSubject承载见 builder.class.ts默认query。两个端点在实际请求中的差异可以从 flushGetContentQueue 看到apiEndpoint query时请求GET /api/v3/query/{apiKey}/{keyNames}响应按 key 组织result[keyName]并自动附带includeRefstruev6.0.0 起用includeRefs取代了原先默认传给 API 的enrichtrueapiEndpoint content时请求GET /api/v3/content/{model}响应为results数组查询参数中的 MongoDB 风格 query 会被 flattenMongoQuery 展平为点号路径v6.1.1 修复了$-mongo 操作符在此端点下的转换问题。测试文件 builder.class.test.ts 精确断言了两种端点最终拼出的 URL例如 content 端点为https://cdn.builder.io/api/v3/content/{MODEL}?...includeRefstruelimit10modelpagequery 端点为https://cdn.builder.io/api/v3/query/{API_KEY}/{MODEL}?...。升级到 6.x 时需要把原来写在get选项里的apiEndpoint迁移为实例属性赋值如builder.apiEndpoint content。三、enrichOptions引用富化的深度与字段级控制v6.2.0 是 CHANGELOG 中体量最大的功能条目enrichOptions参数用于在获取内容时控制引用reference富化的深度与字段选择目标是把按需取数做到字段级。官方给出的两种用法必须完整继承// 基础用法控制富化深度 await builder.getAll(page, { enrich: true, enrichOptions: { enrichLevel: 2, // 获取 2 层嵌套引用 }, }); // 进阶用法按模型选择性包含/排除字段 await builder.getAll(page, { enrich: true, enrichOptions: { enrichLevel: 3, model: { product: { fields: id,name,price, omit: data.internalNotes, }, category: { fields: id,name, }, }, }, });这一 API 的核心语义与约束可以在类型定义 GetContentOptions.enrichOptions 中找到精确说明enrichLevel嵌套引用富化的深度层级。enrichLevel: 1表示在原始响应内再返回一层嵌套模型最大值 4model以模型名为 key 的映射每个模型条目支持fields逗号分隔的包含字段列表与omit逗号分隔的排除字段列表另有可扩展的任意键[key: string]: any注释明确指向 Content API 的enrichOptions文档源码中see链接标注。底层实现上flushGetContentQueue会通过 flattenEnrichOptions 将嵌套对象递归展平为点号查询参数如enrichOptions.enrichLevel3、enrichOptions.model.product.fieldsid,name,price随后在 query 与 content 两种端点上都会附加这些参数见 builder.class.ts 与 builder.class.ts。与之相关的还有两个互补参数源码注释中已标记为弃用includeRefsv2.0.3 起被enrich取代与noTraverse。noTraverse控制是否懒加载 Symbol/引用true时惰性加载false时急切渲染整棵内容树v2.1.0 起getAll在未显式传入时默认置为true以提升查询性能见 builder.class.ts。四、get / getAll 完整参数手册综合 CHANGELOG 与 GetContentOptions 类型定义builder.get(model, options)与builder.getAll(model, options)的选项可按用途分类查询与筛选参数说明queryMongoDB 风格查询对象如{ data.customField.$gt: 100 }sort排序对象值为1升序或-1降序如{ createdDate: 1 }limit/offset分页控制limit默认 1get场景getAll内部默认 30fields/omit响应字段白名单/黑名单omit优先于fieldsContent API 调用默认omit为meta.componentsUsedv6.0.5 起includeUnpublished是否包含未归档的草稿内容默认falsefetchTotalCount为true时返回{ results, totalCount }v6.3.0 起在 gen1 SDK 中可用个性化与上下文参数说明userAttributes自定义定位键值对如{ urlPath: /, returnVisitor: true }urluserAttributes.urlPath的别名可传完整 URLSDK 会解析出 pathlocale当前语言环境用于自动解析本地化输入需与空间配置的 locale 键匹配缓存与性能参数说明cacheSeconds响应缓存秒数设置cache-control的max-agestaleCacheSeconds边缘 stale-while-revalidate 时长建议保持较高值cachebust绕过所有缓存适合开发与静态构建cache客户端是否缓存响应默认truefetchOptions透传给fetch的第二参数v3.0.5 引入渲染相关参数说明prerender将视觉内容转换为 HTML写入data.htmlextractCss生成 HTML 时将样式抽取为独立 css 属性format目标格式可选amp | email | html | react | solidreact/solid会命中/api/v1/codegen端点entry指定要获取的内容条目 ID其他参数说明authToken私有模型获取v2.1.1 起getAll支持key内容缓存键不传时getAll在浏览器端用hash-sum对选项做哈希生成initialContent跳过网络请求直接渲染给定内容SSR 首帧noEditorUpdates嵌入 Symbol 时避免误监听编辑器消息五、视觉编辑器通信安全模型的持续加固CHANGELOG 中另一条高频主线是安全加固涉及宿主页面与 Builder 编辑器 iframe 之间的postMessage信任校验经历了多轮收紧v2.2.0开始更严格地校验 trusted hostsv4.0.1将trustedHost检查覆盖到所有消息v6.0.7再次收紧 trusted origin 校验v6.3.1按精确的可信主机名校验视觉编辑器消息来源并拒绝格式错误或非 HTTP(S) 的 origin。源码中的实现分为两层。第一层是主机名单与匹配trustedHosts 默认包含*.beta.builder.io、beta.builder.io、builder.io、localhost、qa.builder.ioisTrustedHost 支持*.前缀的通配后缀匹配且可用registerTrustedHost追加自定义域名。第二层是事件来源校验isTrustedHostForEvent 要求 origin 必须以http://或https://开头、可解析、协议合法且主机名通过isTrustedHost。对应测试 builder.class.test.ts 覆盖了正反两面的边界localhost、builder.io、123-review-build.beta.builder.io被信任cdn.builder.io、foo.builder.io、evildomainbeta.builder.io后缀伪装的域名、https://evil-builder.io.attacker.com、javascript://builder.io、not a URL、null等全部被拒绝。bindMessageListeners见 builder.class.ts在每一则消息处理前都会先执行该校验未通过直接返回。六、自定义组件注册类型体系与函数序列化的演进Builder.registerComponent(MyComponent, options)是 Builder 生态扩展的入口CHANGELOG 中大量条目围绕其输入 schema 与序列化机制展开。6.1 组件元数据类型的增量补全v6.3.2group?: string。新增到Component元数据允许把自定义组件按相同group值归入编辑器插入菜单的独立手风琴分组未设置或为空时回退到默认的 Custom Components 分组。源码注释中的示例为{ name: Step, group: Steps }见 [builder.class.ts](https://link.gitcode.com/i/0af62c36e086ac12e744c4fd4008414b#L883-L896测试 builder.class.test.ts 验证了该字段在prepareComponentSpecToSend与注册后均被保留——这一设计也避免了 TS 集成时的 excess-property 报错v6.3.3showIf上下文扩展。showIf回调现在能接收现有的父级参数与当前编辑器 locale通过context.locale类型定义见 builder.class.tsv6.0.2folded/keysHelperText。补充到Input类型object类型输入默认折叠以节省编辑区空间并提供对象编辑引导文案builder.class.tsv2.2.2 / v6.0.0meta。先给Input增加meta后给Component增加metaRecordstring, any以承载自定义元数据v6.1.4description。恢复对输入的description支持编辑器 UI 中的说明文案v2.2.3组件类型readonly让注册的组件元数据不可被意外篡改v6.0.2firstPublished加入BuilderContent类型v1.1.33 / v1.1.34responsiveStyles、枚举类型修正修复了 Remix 下的类型检查问题。6.2 onChange 与 previousOptionsv3.0.4 为自定义组件输入的onChange增加了第二个参数previousOptions用于在触发变更前获取旧值onChange?: | ((options: Mapstring, any, previousOptions?: Mapstring, any) void | Promisevoid) | string;v2.0.6 起builder.get可直接awaitv6.0.0 起onChange支持异步函数async functions 也能被正确序列化与执行。6.3 函数序列化机制编辑器与宿主页面通过 postMessage 传输组件规格函数无法直接序列化因此 serializeIncludingFunctions 会把函数体转换为可执行的字符串形式形如return (function(value){...}).apply(this, arguments)并兼容 7 种函数语法普通函数、箭头函数、无括号箭头函数、async 变体等。v3.0.1 起插件注册也会序列化函数使showIf可以作为函数存在v2.2.8 起注册组件信息内的所有函数都被序列化v6.0.8 起插件的函数改为选择性序列化onSave保持为真实函数引用避免破坏插件保存流程。相关测试见 builder.class.test.ts覆盖了 7 种函数形态与onSave保留行为。6.4 动作注册v6.0.9 引入registerActionbuilder.class.ts。Action类型builder.class.ts要求提供全局唯一id、name、输入 schema、返回类型与kindexpression | function | any浏览器端会序列化action函数并通过builder.registerAction消息同步给编辑器。runAction则按名称在已注册动作中查找并执行。七、个性化、定位与国际化SDK 的定位体系围绕UserAttributes展开builder.class.ts它支持 string / boolean / number 及其数组、嵌套对象值核心键是urlPath。getUserAttributes会自动从 UA 推断devicemobile/tablet/desktop与host。v3.0.0 有一个值得注意的破坏性变更userAttributes值由 SDK 内部统一JSON.stringify调用方不应再手动字符串化属性值v2.2.5 曾尝试解析字符串化的数值、v2.2.7 回退、v3.0.0 最终统一标准。v3.0.2 加入内置的个性化容器支持块级block level个性化v4.0.3 修复 locale 处理并让locale在过滤时穿透到个性化容器v5.0.0 之后locale会同时写入查询参数与userAttributes见 builder.class.tssetUserAttributes会在可跟踪时将属性写入builder.userAttributescookie便于个性化容器脚本在 hydration 前读取。八、分析与转化跟踪v6.2.1 / v6.1.3两次修复trackConversion的转化跟踪正确性v6.0.4允许在调用builder.init()之前设置builder.canTrack此前设置会被init的默认值覆盖——这与 init 中的hasOverriddenCanTrack标记配合一旦用户显式赋值init便不再覆盖v1.1.26尊重canTrack为false时不设置会话 cookiev1.1.27停止为没有 id 的内容上报曝光impression并标记Builder.VERSION弃用v2.0.5setServerContext允许在服务端自定义代码绑定custom code bindings的执行上下文基于isolated-vm。跟踪事件会批量入队经throttle后以 5 秒节流 POST 到${host}/api/v1/trackbuilder.class.ts。自 v3.0.6 / v3.0.7 起SDK 还会通过X-Builder-SDK、X-Builder-SDK-GEN、X-Builder-SDK-Version请求头getSdkHeaders向 API 与视觉编辑器上报准确的 npm 包名与版本。九、工程化与运行环境兼容性CHANGELOG 中散布着大量工程细节对选型与排障有直接价值v2.0.8移除setImmediate使用修复 Next.jsedge runtime下的兼容问题v2.2.4isolated-vm升级到 5.0.0加入Node.js v22支持v1.1.34安全地使用 fetch 兜底修复 Salesforce 托管运行时的兼容问题v2.0.7将nx/nx-cloud移出dependencies避免污染生产依赖树v6.0.3内容条目支持xsmall断点尺寸v6.0.6修正defaultStyles的示例appearance、padding、backgroundColor等默认样式键值v6.0.1编辑页面时 Symbol 显示已发布内容而非预览/自动保存内容v2.2.6Embed 的 iframe 生成逻辑迁移到视觉编辑器侧v1.1.30ScrollInView动画新增threshold与repeat输入。另外getAll在服务端会为每次请求新建Builder实例避免跨请求状态污染在浏览器端则复用单例未显式传入key时浏览器端用hash(omit(options, initialContent, req, res))生成缓存键保证相同选项命中同一观察者builder.class.ts。十、版本演进时间线与升级要点把 CHANGELOG 压缩成一张可直接对照的时间线版本段主题升级要点v1.1.x基础能力apiVersion诞生canTrack语义确立Remix/类型修复v2.x服务端能力默认v3enrich取代includeRefsgetAll默认noTraversetrueedge runtime 兼容trusted host 收紧v3.x个性化与类型userAttributes不再手动字符串化破坏性onChange增加previousOptionsfetchOptionsSDK 头v4.x端点调整移除apiEndpoint参数trustedHost 覆盖全部消息v5.0.0端点回退使用/query端点修复 Symbol 渲染破坏性v6.x收敛与安全apiEndpoint移至实例属性破坏性includeRefstrue取代默认enrichtruecanTrack可先于initenrichOptions深度/字段控制group分组showIf接收context.locale升级到 v6.x 时需重点检查三处一是builder.get/builder.getAll选项中的apiEndpoint是否迁移为builder.apiEndpoint实例赋值二是userAttributes传值是否含多余的JSON.stringify三是enrich/includeRefs的默认行为变化是否影响依赖引用内容的页面。源码 builder.class.ts、测试 builder.class.test.ts 与 README packages/core/README.md 可作为排障与行为验证的第一手依据。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考