Builder.io 核心 SDK GetContentOptions 完整指南从内容拉取、定位分页到缓存与 SSR 预渲染【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 的核心 SDK位于packages/core通过builder.getContent(modelName, options)从 Content API 拉取可视化内容。GetContentOptions就是这一方法的核心选项接口它同时驱动了 SDK 的默认getContent与getAll两条内容获取链路。本文将以 GetContentOptions.md 为骨架结合 builder.class.ts 的源码实现逐项拆解全部选项参数、给出可直接运行的调用示例并剖析请求队列、缓存策略与 HTML 预渲染等底层原理帮助你精确掌控 Builder.io 内容获取行为。接口定位与核心用法GetContentOptions在源码中定义为AllowEnrich { ... }的类型builder.class.ts其中AllowEnrich约束了apiVersion与enrich的组合关系v1 与 v3 版本互斥v3 或未指定版本时可使用enrich。它被以下核心 API 使用getContent(modelName, options)获取内容默认只返回 1 条builder.class.tsgetAll(modelName, options)批量获取内部强制limit: 30兜底并默认开启noTraversebuilder.class.tsqueueGetContent(modelName, options)批量请求的内部实现与getContent共用同一选项结构builder.class.ts。典型用法builder.getContent(page, { userAttributes: { urlPath: / }, limit: 1, }).then(content { /* 渲染 content[0] */ });接口共暴露 25 个属性按职责可划分为六大类内容选择、个性化定位、引用富化、缓存控制、HTML 生成、内部专用选项。下面逐一展开。内容选择model、query、entry、fields、omit、limit、offset 与排序model 与 entry确定取什么model: string要获取内容的模型名称如page、product、announcement-bar。这是内容获取的第一筛选维度。entry: string直接指定某条内容条目的 ID 进行精确拉取跳过模型内的规则匹配。queryMongoDB 风格数据查询query直接透传给 Content API采用 MongoDB 查询语法见 builder.class.ts 的源码注释示例builder.getContent(product, { query: { id: abc123, data: { myCustomField: { $gt: 20 }, }, }, });支持 MongoDB 的各类操作符$gt、$lt、$in、$eq等可对条目顶层字段与data自定义字段同时过滤。fields 与 omit字段投影控制fields: string逗号分隔的仅包含字段列表例如id, name, data.customFieldomit: string逗号分隔的排除字段列表例如data.bigField,data.blocks原文档示例。源码注释明确约定omit优先于fieldsbuilder.class.ts。当响应体很大时用omit: data.blocks排除整块可视化布局数据可以显著减小传输体积适合只需要data.html预渲染结果或纯元数据的场景。limit、offset、sort 与分页limit: number最大返回条数默认1offset: number分页偏移量默认0sort: { [key: string]: 1 | -1 }排序键值对1升序、-1降序例如{ createdDate: 1 }builder.class.ts。分页典型写法const page2 await builder.getContent(blog-post, { query: { data.published: true }, sort: { firstPublished: -1 }, limit: 10, offset: 10, // 第二页 });配合getAll还可启用fetchTotalCount: true让响应额外返回匹配总数不受 limit/offset 影响便于构建带页码导航的分页组件builder.class.ts。includeUnpublished纳入草稿默认只返回已发布内容设置includeUnpublished: true后响应会包含仍处于 draft 状态且未归档的条目builder.class.ts适合预览与内容审核场景。个性化定位userAttributes、url 与 localeuserAttributes 与 UserAttributes 接口userAttributes提供当前用户的关键值对用于 Builder 的自定义定向custom targeting。其类型即独立的 UserAttributes 接口builder.class.ts核心字段urlPath?: string当前用户的 URL 路径其余键允许string | string[] | boolean | boolean[] | number | number[] | Recordstring, any例如returnVisitor: true另有大量deprecated hidden的历史字段device、userAgent、referrer、language、newVisitor等不建议在新代码中使用。原文档示例builder.getContent(page, { userAttributes: { urlPath: /, returnVisitor: true, }, });getUserAttributes()在源码中会合并Builder.overrideUserAttributes、Cookie 中的访问者/会话属性与trackingUserAttributesbuilder.class.ts也就是说 SDK 会自动附带会话级属性你只需传入业务相关的定向属性。urlurlPath 的增强别名url是userAttributes.urlPath的别名但更强它可接收带 host、protocol、query 的完整 URLSDK 会自动解析出 pathname 部分再用于匹配builder.class.ts。例如传url: https://example.com/blog/my-post?utm_sourcexx等价于设置urlPath: /blog/my-post。locale多语言自动解析locale: string设置为应用当前语言环境需与空间设置中的某个 locale key 一致即可让本地化localized输入字段在响应中被自动解析为对应语言的值。源码中还会回退到userAttributes.localebuilder.class.tsbuilder.getContent(page, { locale: de-DE, userAttributes: { urlPath: /produkte }, });引用与富化includeRefs、enrich、enrichOptions 与 noTraverseincludeRefs是否跟随 reference 字段当内容条目中使用了reference字段引用其他内容时必须开启includeRefs: true才会在最终响应中拉取被引用的内容否则引用内容不会出现在结果里builder.class.ts。源码注释明确标注该选项已废弃请改用enrich。enrich 与 enrichOptions现代替代方案enrich: boolean通过AllowEnrich类型约束仅在apiVersion: v3或未指定版本时可用enrichOptions.enrichLevel引用富化的嵌套深度最大 4 层enrichOptions.model按被引用模型分别控制字段包含/排除builder.class.tsbuilder.getContent(landing-page, { apiVersion: v3, enrich: true, enrichOptions: { enrichLevel: 2, model: { product: { fields: id,name,price, omit: data.internalNotes }, category: { fields: id,name }, }, }, });源码中flattenEnrichOptions会把嵌套的enrichOptions对象递归压平为点号形式的查询参数如enrichOptions.model.product.fields再附加到请求上builder.class.ts。noTraverse懒加载引用noTraverse: true时符号/引用将被懒加载而非急切渲染整棵内容树已废弃同样建议改用enrich。值得注意getAll在用户未显式传入时会默认强制设置noTraverse: true以提升查询性能builder.class.ts。缓存控制cache、cacheSeconds、staleCacheSeconds、cachebust 与 revBuilder.io 的缓存体系分两层客户端内存/持久缓存 CDN 边缘缓存。cache客户端缓存开关cache: boolean设为false时客户端将不缓存响应builder.class.ts。默认开启适合内容更新不频繁的页面。cacheSecondsCache-Control 有效期cacheSeconds: number设置内容缓存秒数并直接映射为响应的Cache-Control: max-age头builder.class.ts。原文档提示值越大性能越好值越小内容更新越快——生产环境取较高值内容频繁变动的场景取较低值。staleCacheSecondsstale-while-revalidatestaleCacheSeconds: number对应 Builder 在 CDN 层使用的stale-while-revalidate策略始终从边缘缓存即时返回同时在后台刷新缓存实现最大性能请求越频繁内容越新鲜。默认最长滞留 stale 缓存1 天你可以调短builder.class.ts。原文档建议除非内容必须极快更新且流量很低否则保持较高的值。cachebust穿透所有缓存cachebust: boolean强制穿透全部缓存层不推荐生产使用性能差但在开发调试和静态构建时很有用——确保静态站点拿到完全新鲜的内容builder.class.ts。rev基于版本的缓存击穿rev: string是内部package缓存击穿串每次生成 HTML 时会产生一个修订 IDrev并随客户端请求发送一旦服务端生成了新 HTML客户端拿到新 rev 即可击穿缓存——即使内容 ID 相同也可能是已更新的版本builder.class.ts。这解决了同 ID 内容更新后客户端仍命中旧缓存的问题。HTML 生成prerender、extractCss、format 与 static这些选项服务于把可视化内容转为 HTML的服务端/构建期渲染链路。prerender内容转 HTMLprerender: boolean将可视化构建的内容转换为 HTML转换结果放在响应条目对象 JSON 的data.html字段中builder.class.ts。这是 SSR / SSG 场景的核心开关。extractCss样式分离extractCss: boolean在生成 HTML 时把样式抽取到独立的css属性中便于提取关键 CSS、做样式去重或内联优化builder.class.ts。format目标格式format: amp | email | html | react | solid影响针对特定目标的 HTML 生成builder.class.ts例如 AMP 页面、邮件模板、React/Solid 组件等场景。staticAB 测试静态模式static: boolean指示 API 以静态模式生成 HTML 以适配 A/B 测试替代旧的生成方式内部package专用builder.class.ts。典型 SSR 组合// 服务端获取已渲染 HTML配合 extractCss 抽取样式 builder.getContent(page, { userAttributes: { urlPath: req.path }, prerender: true, extractCss: true, cacheSeconds: 3600, });内部专用参数initialContent、noEditorUpdates、preview、includeUrl、options 与 key以下参数均标记package主要供 SDK 内部或编辑器场景使用普通业务代码一般无需手动设置initialContent: any提供一段BuilderContent直接用于渲染跳过网络请求——典型用于编辑器实时预览或 SSR 水合builder.class.tsnoEditorUpdates: boolean不监听编辑器更新消息防止嵌入的 Symbol 在编辑内容时误收消息而错误刷新builder.class.tspreview: boolean标记该次请求为预览用途builder.class.tsincludeUrl: boolean是否在响应中附带 URL 相关信息options: { [key: string]: any }向 Content API 追加任意额外查询参数builder.class.tskey: string请求缓存键。getAll中当options.key缺失时会用hash(omit(options, initialContent, req, res))自动生成保证相同参数命中同一缓存builder.class.ts。底层调用链从 getContent 到请求队列理解GetContentOptions如何被消费可以沿调用链深入getContent(modelName, options)首先校验apiKey是否已初始化未设置则直接抛错builder.class.ts随后委托给queueGetContent(modelName, options)将{ ...options, model: modelName, key }推入getContentQueue队列当队列长度达到contentPerRequest阈值时一次性批量发出builder.class.ts——这是 SDK 通过请求合并降低并发请求数的优化flushGetContentQueue最终把队列里的每个选项构造成 Content API 查询含 userAttributes 合并、分页、字段投影等getAll还会在其上强制limit: 30兜底与noTraverse: truebuilder.class.ts。这意味着即便你调用多次getContentSDK 也会尽量合并为少量 HTTP 请求cacheSeconds/staleCacheSeconds/rev等参数则直接决定了这些请求的缓存命中率与新鲜度。参数速查表参数类型默认值用途modelstring-要获取内容的模型名entrystring-精确获取指定内容条目 IDqueryany-MongoDB 风格数据过滤fields/omitstring-字段包含 / 排除omit 优先limitnumber1最大返回条数offsetnumber0分页偏移sortobject-按字段排序1 / -1userAttributesUserAttributes-用户属性用于定向urlstring-urlPath别名可传完整 URLlocalestring-本地化输入自动解析includeRefsbooleanfalse跟随 reference已废弃用 enrichenrichbooleanfalse引用富化v3enrichOptionsobject-富化深度与按模型字段控制noTraverseboolean-懒加载引用已废弃cachebooleantrue客户端响应缓存开关cacheSecondsnumber-Cache-Control max-age 秒数staleCacheSecondsnumber1 天CDN 层 stale-while-revalidate 时长cachebustbooleanfalse穿透所有缓存慎用revstring-版本化缓存击穿串内部prerenderbooleanfalse转 HTML结果在data.htmlextractCssbooleanfalse生成 HTML 时抽取独立样式formatstring-amp/email/html/react/solidstaticbooleanfalseAB 测试静态模式内部initialContentany-直接渲染指定内容跳过请求内部noEditorUpdatesbooleanfalse不监听编辑器更新内部preview/includeUrlbooleanfalse预览标记 / 附带 URL内部optionsobject-追加任意 Content API 查询参数keystring自动生成请求缓存键完整实战示例一个结合定位、分页、富化与缓存的综合调用// pages/api/products.jsNext.js API 路由等场景 import { builder } from builder.io/sdk; export default async function handler(req, res) { const products await builder.getAll(product, { apiVersion: v3, userAttributes: { urlPath: req.url }, query: { data.active: { $eq: true } }, sort: { firstPublished: -1 }, limit: 12, offset: (Number(req.query.page) || 1 - 1) * 12, fields: id,name,data.price,data.blocks, enrich: true, enrichOptions: { enrichLevel: 1 }, cacheSeconds: 300, staleCacheSeconds: 1800, fetchTotalCount: true, }); res.json(products); // { results, totalCount } }使用注意事项废弃选项includeRefs、noTraverse、alias、noWrap已在源码中标记deprecated或hiddenbuilder.class.ts新项目统一使用enrichenrichOptions版本约束enrich仅在apiVersion: v3或未指定下可用v1 请求不允许携带该参数AllowEnrich类型会在编译期拦截字段投影优先级同时设置fields与omit时omit生效缓存权衡cachebust只用于开发与静态构建生产环境应通过cacheSeconds/staleCacheSeconds平衡性能与新鲜度服务端要求getContent在任何环境都会校验apiKey未初始化直接抛错builder.class.ts。掌握GetContentOptions的全部选项你就能针对页面渲染、列表分页、A/B 测试、多语言站点与 SSR/SSG 构建分别定制最优的内容获取策略同时借助请求队列与多级缓存让内容拉取既快又新。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Builder.io 核心 SDK GetContentOptions 完整指南：从内容拉取、定位分页到缓存与 SSR 预渲染
Builder.io 核心 SDK GetContentOptions 完整指南从内容拉取、定位分页到缓存与 SSR 预渲染【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 的核心 SDK位于packages/core通过builder.getContent(modelName, options)从 Content API 拉取可视化内容。GetContentOptions就是这一方法的核心选项接口它同时驱动了 SDK 的默认getContent与getAll两条内容获取链路。本文将以 GetContentOptions.md 为骨架结合 builder.class.ts 的源码实现逐项拆解全部选项参数、给出可直接运行的调用示例并剖析请求队列、缓存策略与 HTML 预渲染等底层原理帮助你精确掌控 Builder.io 内容获取行为。接口定位与核心用法GetContentOptions在源码中定义为AllowEnrich { ... }的类型builder.class.ts其中AllowEnrich约束了apiVersion与enrich的组合关系v1 与 v3 版本互斥v3 或未指定版本时可使用enrich。它被以下核心 API 使用getContent(modelName, options)获取内容默认只返回 1 条builder.class.tsgetAll(modelName, options)批量获取内部强制limit: 30兜底并默认开启noTraversebuilder.class.tsqueueGetContent(modelName, options)批量请求的内部实现与getContent共用同一选项结构builder.class.ts。典型用法builder.getContent(page, { userAttributes: { urlPath: / }, limit: 1, }).then(content { /* 渲染 content[0] */ });接口共暴露 25 个属性按职责可划分为六大类内容选择、个性化定位、引用富化、缓存控制、HTML 生成、内部专用选项。下面逐一展开。内容选择model、query、entry、fields、omit、limit、offset 与排序model 与 entry确定取什么model: string要获取内容的模型名称如page、product、announcement-bar。这是内容获取的第一筛选维度。entry: string直接指定某条内容条目的 ID 进行精确拉取跳过模型内的规则匹配。queryMongoDB 风格数据查询query直接透传给 Content API采用 MongoDB 查询语法见 builder.class.ts 的源码注释示例builder.getContent(product, { query: { id: abc123, data: { myCustomField: { $gt: 20 }, }, }, });支持 MongoDB 的各类操作符$gt、$lt、$in、$eq等可对条目顶层字段与data自定义字段同时过滤。fields 与 omit字段投影控制fields: string逗号分隔的仅包含字段列表例如id, name, data.customFieldomit: string逗号分隔的排除字段列表例如data.bigField,data.blocks原文档示例。源码注释明确约定omit优先于fieldsbuilder.class.ts。当响应体很大时用omit: data.blocks排除整块可视化布局数据可以显著减小传输体积适合只需要data.html预渲染结果或纯元数据的场景。limit、offset、sort 与分页limit: number最大返回条数默认1offset: number分页偏移量默认0sort: { [key: string]: 1 | -1 }排序键值对1升序、-1降序例如{ createdDate: 1 }builder.class.ts。分页典型写法const page2 await builder.getContent(blog-post, { query: { data.published: true }, sort: { firstPublished: -1 }, limit: 10, offset: 10, // 第二页 });配合getAll还可启用fetchTotalCount: true让响应额外返回匹配总数不受 limit/offset 影响便于构建带页码导航的分页组件builder.class.ts。includeUnpublished纳入草稿默认只返回已发布内容设置includeUnpublished: true后响应会包含仍处于 draft 状态且未归档的条目builder.class.ts适合预览与内容审核场景。个性化定位userAttributes、url 与 localeuserAttributes 与 UserAttributes 接口userAttributes提供当前用户的关键值对用于 Builder 的自定义定向custom targeting。其类型即独立的 UserAttributes 接口builder.class.ts核心字段urlPath?: string当前用户的 URL 路径其余键允许string | string[] | boolean | boolean[] | number | number[] | Recordstring, any例如returnVisitor: true另有大量deprecated hidden的历史字段device、userAgent、referrer、language、newVisitor等不建议在新代码中使用。原文档示例builder.getContent(page, { userAttributes: { urlPath: /, returnVisitor: true, }, });getUserAttributes()在源码中会合并Builder.overrideUserAttributes、Cookie 中的访问者/会话属性与trackingUserAttributesbuilder.class.ts也就是说 SDK 会自动附带会话级属性你只需传入业务相关的定向属性。urlurlPath 的增强别名url是userAttributes.urlPath的别名但更强它可接收带 host、protocol、query 的完整 URLSDK 会自动解析出 pathname 部分再用于匹配builder.class.ts。例如传url: https://example.com/blog/my-post?utm_sourcexx等价于设置urlPath: /blog/my-post。locale多语言自动解析locale: string设置为应用当前语言环境需与空间设置中的某个 locale key 一致即可让本地化localized输入字段在响应中被自动解析为对应语言的值。源码中还会回退到userAttributes.localebuilder.class.tsbuilder.getContent(page, { locale: de-DE, userAttributes: { urlPath: /produkte }, });引用与富化includeRefs、enrich、enrichOptions 与 noTraverseincludeRefs是否跟随 reference 字段当内容条目中使用了reference字段引用其他内容时必须开启includeRefs: true才会在最终响应中拉取被引用的内容否则引用内容不会出现在结果里builder.class.ts。源码注释明确标注该选项已废弃请改用enrich。enrich 与 enrichOptions现代替代方案enrich: boolean通过AllowEnrich类型约束仅在apiVersion: v3或未指定版本时可用enrichOptions.enrichLevel引用富化的嵌套深度最大 4 层enrichOptions.model按被引用模型分别控制字段包含/排除builder.class.tsbuilder.getContent(landing-page, { apiVersion: v3, enrich: true, enrichOptions: { enrichLevel: 2, model: { product: { fields: id,name,price, omit: data.internalNotes }, category: { fields: id,name }, }, }, });源码中flattenEnrichOptions会把嵌套的enrichOptions对象递归压平为点号形式的查询参数如enrichOptions.model.product.fields再附加到请求上builder.class.ts。noTraverse懒加载引用noTraverse: true时符号/引用将被懒加载而非急切渲染整棵内容树已废弃同样建议改用enrich。值得注意getAll在用户未显式传入时会默认强制设置noTraverse: true以提升查询性能builder.class.ts。缓存控制cache、cacheSeconds、staleCacheSeconds、cachebust 与 revBuilder.io 的缓存体系分两层客户端内存/持久缓存 CDN 边缘缓存。cache客户端缓存开关cache: boolean设为false时客户端将不缓存响应builder.class.ts。默认开启适合内容更新不频繁的页面。cacheSecondsCache-Control 有效期cacheSeconds: number设置内容缓存秒数并直接映射为响应的Cache-Control: max-age头builder.class.ts。原文档提示值越大性能越好值越小内容更新越快——生产环境取较高值内容频繁变动的场景取较低值。staleCacheSecondsstale-while-revalidatestaleCacheSeconds: number对应 Builder 在 CDN 层使用的stale-while-revalidate策略始终从边缘缓存即时返回同时在后台刷新缓存实现最大性能请求越频繁内容越新鲜。默认最长滞留 stale 缓存1 天你可以调短builder.class.ts。原文档建议除非内容必须极快更新且流量很低否则保持较高的值。cachebust穿透所有缓存cachebust: boolean强制穿透全部缓存层不推荐生产使用性能差但在开发调试和静态构建时很有用——确保静态站点拿到完全新鲜的内容builder.class.ts。rev基于版本的缓存击穿rev: string是内部package缓存击穿串每次生成 HTML 时会产生一个修订 IDrev并随客户端请求发送一旦服务端生成了新 HTML客户端拿到新 rev 即可击穿缓存——即使内容 ID 相同也可能是已更新的版本builder.class.ts。这解决了同 ID 内容更新后客户端仍命中旧缓存的问题。HTML 生成prerender、extractCss、format 与 static这些选项服务于把可视化内容转为 HTML的服务端/构建期渲染链路。prerender内容转 HTMLprerender: boolean将可视化构建的内容转换为 HTML转换结果放在响应条目对象 JSON 的data.html字段中builder.class.ts。这是 SSR / SSG 场景的核心开关。extractCss样式分离extractCss: boolean在生成 HTML 时把样式抽取到独立的css属性中便于提取关键 CSS、做样式去重或内联优化builder.class.ts。format目标格式format: amp | email | html | react | solid影响针对特定目标的 HTML 生成builder.class.ts例如 AMP 页面、邮件模板、React/Solid 组件等场景。staticAB 测试静态模式static: boolean指示 API 以静态模式生成 HTML 以适配 A/B 测试替代旧的生成方式内部package专用builder.class.ts。典型 SSR 组合// 服务端获取已渲染 HTML配合 extractCss 抽取样式 builder.getContent(page, { userAttributes: { urlPath: req.path }, prerender: true, extractCss: true, cacheSeconds: 3600, });内部专用参数initialContent、noEditorUpdates、preview、includeUrl、options 与 key以下参数均标记package主要供 SDK 内部或编辑器场景使用普通业务代码一般无需手动设置initialContent: any提供一段BuilderContent直接用于渲染跳过网络请求——典型用于编辑器实时预览或 SSR 水合builder.class.tsnoEditorUpdates: boolean不监听编辑器更新消息防止嵌入的 Symbol 在编辑内容时误收消息而错误刷新builder.class.tspreview: boolean标记该次请求为预览用途builder.class.tsincludeUrl: boolean是否在响应中附带 URL 相关信息options: { [key: string]: any }向 Content API 追加任意额外查询参数builder.class.tskey: string请求缓存键。getAll中当options.key缺失时会用hash(omit(options, initialContent, req, res))自动生成保证相同参数命中同一缓存builder.class.ts。底层调用链从 getContent 到请求队列理解GetContentOptions如何被消费可以沿调用链深入getContent(modelName, options)首先校验apiKey是否已初始化未设置则直接抛错builder.class.ts随后委托给queueGetContent(modelName, options)将{ ...options, model: modelName, key }推入getContentQueue队列当队列长度达到contentPerRequest阈值时一次性批量发出builder.class.ts——这是 SDK 通过请求合并降低并发请求数的优化flushGetContentQueue最终把队列里的每个选项构造成 Content API 查询含 userAttributes 合并、分页、字段投影等getAll还会在其上强制limit: 30兜底与noTraverse: truebuilder.class.ts。这意味着即便你调用多次getContentSDK 也会尽量合并为少量 HTTP 请求cacheSeconds/staleCacheSeconds/rev等参数则直接决定了这些请求的缓存命中率与新鲜度。参数速查表参数类型默认值用途modelstring-要获取内容的模型名entrystring-精确获取指定内容条目 IDqueryany-MongoDB 风格数据过滤fields/omitstring-字段包含 / 排除omit 优先limitnumber1最大返回条数offsetnumber0分页偏移sortobject-按字段排序1 / -1userAttributesUserAttributes-用户属性用于定向urlstring-urlPath别名可传完整 URLlocalestring-本地化输入自动解析includeRefsbooleanfalse跟随 reference已废弃用 enrichenrichbooleanfalse引用富化v3enrichOptionsobject-富化深度与按模型字段控制noTraverseboolean-懒加载引用已废弃cachebooleantrue客户端响应缓存开关cacheSecondsnumber-Cache-Control max-age 秒数staleCacheSecondsnumber1 天CDN 层 stale-while-revalidate 时长cachebustbooleanfalse穿透所有缓存慎用revstring-版本化缓存击穿串内部prerenderbooleanfalse转 HTML结果在data.htmlextractCssbooleanfalse生成 HTML 时抽取独立样式formatstring-amp/email/html/react/solidstaticbooleanfalseAB 测试静态模式内部initialContentany-直接渲染指定内容跳过请求内部noEditorUpdatesbooleanfalse不监听编辑器更新内部preview/includeUrlbooleanfalse预览标记 / 附带 URL内部optionsobject-追加任意 Content API 查询参数keystring自动生成请求缓存键完整实战示例一个结合定位、分页、富化与缓存的综合调用// pages/api/products.jsNext.js API 路由等场景 import { builder } from builder.io/sdk; export default async function handler(req, res) { const products await builder.getAll(product, { apiVersion: v3, userAttributes: { urlPath: req.url }, query: { data.active: { $eq: true } }, sort: { firstPublished: -1 }, limit: 12, offset: (Number(req.query.page) || 1 - 1) * 12, fields: id,name,data.price,data.blocks, enrich: true, enrichOptions: { enrichLevel: 1 }, cacheSeconds: 300, staleCacheSeconds: 1800, fetchTotalCount: true, }); res.json(products); // { results, totalCount } }使用注意事项废弃选项includeRefs、noTraverse、alias、noWrap已在源码中标记deprecated或hiddenbuilder.class.ts新项目统一使用enrichenrichOptions版本约束enrich仅在apiVersion: v3或未指定下可用v1 请求不允许携带该参数AllowEnrich类型会在编译期拦截字段投影优先级同时设置fields与omit时omit生效缓存权衡cachebust只用于开发与静态构建生产环境应通过cacheSeconds/staleCacheSeconds平衡性能与新鲜度服务端要求getContent在任何环境都会校验apiKey未初始化直接抛错builder.class.ts。掌握GetContentOptions的全部选项你就能针对页面渲染、列表分页、A/B 测试、多语言站点与 SSR/SSG 构建分别定制最优的内容获取策略同时借助请求队列与多级缓存让内容拉取既快又新。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
