# @contentful/optimization-node 中文文档 规范地址：https://npmcn.com/package/%40contentful/optimization-node/ 版本：2\.2\.1 npm 元数据更新时间：2026-11-06T12:29:48.826Z 中文译文更新时间：2026-11-10T19:09:46.099Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40contentful/optimization-node 原文对照：https://npmcn.com/package/%40contentful/optimization-node/?lang=original 项目主页：https://github.com/contentful/optimization#readme 源码仓库：https://github.com/contentful/optimization ## 关键信息（来自 npm 元数据） - 包体积（解压后）：200 kB，42 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-02-03T12:39:34.485Z - 最新版本发布：2026-11-06T12:29:48.617Z - 近 30 天下载量：3691（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：28（近 12 个月 28 个） ## 中文简介 内容优化节点.js SDK ## 安装 ```sh npm install @contentful/optimization-node ``` 也可以使用：`pnpm add @contentful/optimization-node`、`yarn add @contentful/optimization-node`、`bun add @contentful/optimization-node` ## README [![Contentful Logo](https://raw.githubusercontent.com/contentful/optimization/optimization-node-v2.2.1/contentful-icon.png "Contentful")](https://www.contentful.com/developers/docs/personalization/) # 内容个性化分析 ### 优化节点 SDK [指南](https://contentful.github.io/optimization/documents/Documentation.Guides.html) • 妇女 [参考文献](https://contentful.github.io/optimization) • 妇女 [捐款](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/CONTRIBUTING.md) 优化节点 SDK 在顶端执行无国籍服务器端优化行为 [优化核心 SDK](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/packages/universal/core-sdk/README.md)。用于服务器渲染、服务器 ,以及需要请求范围剖面评价或事件排放的节点服务. 如果您正在整合一个节点应用程序, 请从 [开始](https://npmcn.com/package/%40contentful/optimization-node/#readme-getting-started),然后使用 [将优化节点SDK整合到节点应用中](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html) 为分步流出. 此 README 保持软件包取向和常见设置选项的关闭 手动; 生成 [参考文件](https://contentful.github.io/optimization) 仍为 导出 API 签名的真伪来源 . > \[大 > > 从v1升级? 跟着 [v1-v2 迁移指南](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) 在更改软件包版本之前. 目录 - [开始](https://npmcn.com/package/%40contentful/optimization-node/#readme-getting-started) - [何时使用此软件包](https://npmcn.com/package/%40contentful/optimization-node/#readme-when-to-use-this-package) - [通用配置](https://npmcn.com/package/%40contentful/optimization-node/#readme-common-configuration) - [核心工作流程](https://npmcn.com/package/%40contentful/optimization-node/#readme-core-workflows) - [请求范围的活动](https://npmcn.com/package/%40contentful/optimization-node/#readme-request-scoped-events) - [内容分辨率](https://npmcn.com/package/%40contentful/optimization-node/#readme-content-resolution) - [缓存引导](https://npmcn.com/package/%40contentful/optimization-node/#readme-caching-guidance) - [利用发展](https://npmcn.com/package/%40contentful/optimization-node/#readme-development-harness) - [相关](https://npmcn.com/package/%40contentful/optimization-node/#readme-related) ## 开始 使用与国家预防机制兼容的软件包管理器安装,例如: ```sh pnpm add @contentful/optimization-node ``` 添加 `contentful` 当SDK会使用你的应用软件时 `contentful.js` 用于管理条目的客户端 取来. 导入优化类;支持CJS和无害环境管理模块系统,无害环境管理优先: ```ts import ContentfulOptimization from '@contentful/optimization-node' ``` 每个模块或进程创建一次SDK,然后在每个路由中绑定同意并请求上下文: ```ts const optimization = new ContentfulOptimization({ spaceId: 'your-space-id', environment: 'master', locale: 'en-US', }) function appPolicyAllowsOptimizationEvent(req: { cookies?: Record }): boolean { return req.cookies?.['app-personalization-consent'] === 'granted' } async function renderRequest( req: { cookies?: Record; headers: { 'accept-language'?: string } }, profileId: string, ) { const appLocale = getAppLocale(req) const requestOptimization = optimization.forRequest({ consent: { events: appPolicyAllowsOptimizationEvent(req), persistence: appPolicyAllowsOptimizationEvent(req), }, locale: appLocale, eventContext: { locale: appLocale }, profileId, }) const { accepted, data } = await requestOptimization.page() return accepted ? data : undefined } ``` ## 何时使用此软件包 使用 `@contentful/optimization-node` 用于服务器侧渲染、服务器功能和节点服务 需要无国籍人特征评估或事件排放。 使用Web 或 反应Web SDK并列 当浏览器侧面同意、匿名ID持续、自动交互跟踪或实时更新时 属于同一应用程序的一部分. ## 通用配置 节点SDK是无国籍的 它不维持同意、配置或浏览器持续状态 在请求之间。 关于跨 SDK 同意指南,见 [优化SDK套件中的同意管理](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md)。 。 。 . | 选项 | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `spaceId` | 对 | 不详 | 用于体验和透视 API 请求的空间标识符 | | `environment` | 没有 | `'master'` | 用于经验与洞察 API 请求的内容环境标识符 | | `api` | 没有 | 参见下面的 API 选项 | API 和 Insights API 端点选项 | | `app` | 没有 | `undefined` | 将事件上下文附加的应用程序元数据 | | `contentful` | 没有 | `undefined` | 注册 `contentful.js` 客户端、 默认查询和缓存 | | `locale` | 没有 | `undefined` | 默认 SDK API 和事件本地化经验 | | `fetchOptions` | 没有 | SDK 默认 | 获取超时并重试行为 | | `allowedEventTypes` | 没有 | `['identify', 'page']` | 批准请求前允许的事件类型 | | `eventBuilder` | 没有 | 节点 SDK 默认 | SDK级作者的事件元数据覆盖 | | `logLevel` | 没有 | `'error'` | 默认控制台槽的最低日志级别 | 常见 `api` 选项: | 选项 | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `experienceBaseUrl` | 没有 | `'https://experience.ninetailed.co/'` | 经验 API 的基础 URL | | `insightsBaseUrl` | 没有 | `'https://ingest.insights.ninetailed.co/'` | 透视 API 的基础 URL | | `enabledFeatures` | 没有 | `['ip-enrichment', 'location']` | 适用于每项请求的 API 特性 | | `location` | 没有 | API 倒计时 | 单向可见体验 API 变异的默认位置 | 请求范围的经验选项包含在 `experienceOptions` 当创建请求绑定时 客户端 : | 选项 | 说明 | | --- | --- | | `ip` | 经验 API 使用的 IP 地址覆盖 | | `location` | 请求更换完整的位置 `api.location` 默认 | | `locale` | 本地化经验的本地化查询参数 | | `plainText` | 发送性能关键体验 API 端点作为文本 | | `preflight` | 汇总新配置文件状态而不存储 | 配置共享默认值 `api.location`,然后以 `experienceOptions.location`数字 : ```ts const optimization = new ContentfulOptimization({ spaceId: 'your-space-id', api: { location: { countryCode: 'DE', city: 'Berlin' } }, }) const requestOptimization = optimization.forRequest({ consent: true, experienceOptions: { location: { countryCode: 'FR', city: 'Paris' } }, }) await requestOptimization.page() ``` 请求值取代整个默认对象;它不会合并字段. 过 `experienceOptions: { location: {} }` 将配置的默认值替换为正空 位置而不是 API 地理定位。 活动 `context.location` 优先于匹配 请求字段。 空位置无法清除现有的配置文件位置, 并请求位置 不将位置锁定在以后的请求中。 见 [位置输入和简介更新](https://contentful.github.io/optimization/documents/Documentation.Concepts.Profile_synchronization_between_client_and_server.html#location-inputs-and-profile-updates)。 。 。 . 请求范围透视选项属于 `insightsOptions`数字 : | 选项 | 说明 | | --- | --- | | `beacon` | 如果需要, 序列式 Insights API 批次的最后发件人 . | 使用请求范围顶层 `locale` 打开 `forRequest()` 作为促进本地化的路径 体验 API 响应和默认事件上下文 . `experienceOptions.locale` 现为 高级低层通过,当 `locale` 未提供。 如果两者均提供,则请求 `locale` 赢了. 常见 `fetchOptions` 为: `fetchMethod`, (中文(简体) ), `requestTimeout`, (中文(简体) ), `retries`, (中文(简体) ), `intervalTimeout`, (中文(简体) ), `onFailedAttempt`,以及 `onRequestTimeout`。默认重试仅对 HTTP 适用 `503` 回应. 在路由器中选择应用程序 Contentful locale, i18n 层, 或者请求策略 。 传过去 值直接输入内容 CDA 请求,并将相同值传递给 `forRequest({ locale: appLocale })` aPI响应和事件背景应使用 同样的语言。 合并引用本地化配置字段的标签, 如 `location.city` 财务报告和审定财务报表 `location.country` 然后用符合所提供内容的语言解决。 见 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 为完整的地方模型. 对于每个选项,回调有效载荷和输出类型,使用生成的 [节点 SDK 参考](https://contentful.github.io/optimization/modules/_contentful_optimization-node.html)。 。 。 . ## 核心工作流程 ### 请求范围的活动 从收到的请求中构建事件上下文,将应用程序拥有的同意状态与 `forRequest()`,然后调用 `page()`, (中文(简体) ), `identify()`, (中文(简体) ), `screen()`, (中文(简体) ), `track()`,或粘着 `trackView()` 打开 返回的请求对象 : ```ts import type { Request } from 'express' app.get('/products/:slug', async (req, res) => { const appLocale = getAppLocale(req) const requestOptimization = optimization.forRequest({ consent: { events: appPolicyAllowsOptimizationEvent(req), persistence: appPolicyAllowsOptimizationEvent(req), }, locale: appLocale, eventContext: { locale: appLocale, }, profileId: req.cookies.profileId, }) const { accepted, data: optimizationData } = await requestOptimization.page({ properties: { path: req.path }, }) if (accepted && requestOptimization.canPersistProfile && optimizationData?.profile.id) { persistProfileId(res, optimizationData.profile.id) } res.render('product', { optimizationData }) }) ``` 对于不使最终用户同意的默认应用政策,替换 接受同意后的特定请求同意查询: ```ts const requestOptimization = optimization.forRequest({ consent: { events: true, persistence: true }, locale: appLocale, eventContext: { locale: appLocale }, profile, }) ``` 节点 SDK事件调用失败, 除了默认的事先同意的许可列表, `identify` 财务报告和审定财务报表 `page`。允许列入清单的事件与 `context.gdpr.isConsentGiven: false` 请求时 不给予同意。 过 `allowedEventTypes: []` 需要严格的选择进入 无国籍事件方法. 在无国籍的运行时间, 非粘滞 `trackView`, (中文(简体) ), `trackClick`, (中文(简体) ), `trackHover`,以及 `trackFlagView` 需要一个完整的 `Profile` 通过 `forRequest({ profile })` 或由经验返回 调用同一请求客户端。 使用 `profileId` aPI的连续性. 对于提交前需要事件有效载荷的自定义集成,使用请求客户端的 `eventBuilder`它会暴露 `buildIdentify`, (中文(简体) ), `buildPageView`, (中文(简体) ), `buildScreenView`,以及 `buildTrack` 带有请求事件上下文和语言默认值。 在这个例子中, `appConsent`, (中文(简体) ), `appLocale`, (中文(简体) ), `appUserAgent`,以及 `appUserId` 来源于您的申请请求和身份处理: ```ts const requestOptimization = optimization.forRequest({ consent: appConsent, locale: appLocale, eventContext: { userAgent: appUserAgent }, }) const identifyEvent = requestOptimization.eventBuilder.buildIdentify({ userId: appUserId }) ``` 建筑不发送事件、检查请求同意、援引拦截器或更新 请求配置或选择。 新建活动使用共享构建器 `context.gdpr.isConsentGiven`, (中文(简体) ), 这是 `false` 在节点SDK中,即使请求得到同意。 发送 `identifyEvent` 通过a 低级API不自动应用请求同意或SDK提交处理. 为了正常 提交, 使用请求 `identify()`, (中文(简体) ), `page()`, (中文(简体) ), `screen()`,或 `track()`单子 `optimization.eventBuilder` 任何要求都不受约束. ### 内容分辨率 当a `contentful.js` 客户端是可用的, 倾向于通过条目 ID 或内容类型获取 SDK 管理 还有口水 配置客户端一次, 然后调用 `fetchOptimizedEntry()` 在请求中的客户端上 在被接受的经验API呼叫后. `forRequest()` 客户端使用最新的选中优化 省去时; 单通呼叫需要明确 `selectedOptimizations`。 。 。 . ```ts const optimization = new ContentfulOptimization({ spaceId: 'space-id', contentful: { client: contentfulClient }, environment: 'master', locale: appLocale, }) const requestOptimization = optimization.forRequest({ consent: true, profile }) await requestOptimization.page() const { baselineEntry, entry } = await requestOptimization.fetchOptimizedEntry({ contentType: 'productPage', slug: req.params.slug, entryQuery: { locale: appLocale }, }) ``` 使用 `fetchContentfulEntries()` 或者说 `prefetchManagedEntries()` 当一个路由知道几个管理 输入来源。 弹出源接受 `slugField` 当内容模型不使用默认值时 `slug` 字段。 Slug 搜索执行内容类型、 字段选择器和双结果独有性限制 合并后 `entryQuery`;成功解析使用已获取条目的 `sys.id`. 分红 将规范化描述符嵌入 `managedEntry` 并保留该ID `entryId`. 同等身份证明 来源保留同干分批和100ID分块. 如果您的应用程序已经获取基线条目, 请继续使用手动解析器 : ```ts const pageResult = await requestOptimization.page() const resolvedEntry = optimization.resolveOptimizedEntry( baselineEntry, pageResult.accepted ? pageResult.data.selectedOptimizations : undefined, ) ``` 在任意一条路径中使用一个 CDA 语言 。 对于本地化的应用程序,请配置您的应用程序本地化 。 A 类 请求的客户端用途 `forRequest({ locale: appLocale })` 作为管理内容查询区域 当两个 `contentful.defaultQuery` 或每个呼叫的查询集 `locale`。将相同的值传递给 应用自有内容 CDA 请求和 `forRequest({ locale: appLocale })` 当合并标签时 读取本地化配置字段与已提供条目语言相匹配。 不通过全本地 CDA 答复 `withAllLocales` 或者说 `locale=*`; 解析器期望直接的单地字段 数值。 见 [条目个性化和变异分辨率](https://contentful.github.io/optimization/documents/Documentation.Concepts.Entry_personalization_and_variant_resolution.html#single-locale-cda-entry-contract) 进入合同和 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 用于请求语言行为. 使用 `getMergeTagValue()` 富足富贵 文本合并标签和 `getFlag()` 自定义旗帜。 如果有的话 合并标签引用本地化配置字段, 如 `location.city` 或者说 `location.country`页:1 解析值遵循经验API返回的本地化配置数据。 节点SDK是 无国籍,所以 `getFlag()` 不自动放出旗帜视图跟踪. ### 缓存引导 应用层或SDK管理条目的内含载荷 缓存, 不是配置文件评价的 SDK 事件结果 。 使用 `clearContentfulEntryCache()` 当 SDK 时 实例必须删除缓存的 CDA 条目. | 数据或呼叫 | 请求缓存? | 原因 | | --- | --- | --- | | 从 CDA 或 SDK 管理的条目缓存获取的原始内容条目 | 对 | 它们是内容快照,可以按请求解决 | | `resolveOptimizedEntry()` 财务报告和审定财务报表 `getMergeTagValue()` 结果 | 仅当地请求 | 结果取决于当前概况和优化数据 | | `page()`, (中文(简体) ), `identify()`, (中文(简体) ), `screen()`, (中文(简体) ), `track()`粘贴 `trackView()` | 没有 | 这些调用执行副作用和返回请求特定配置 | | 非粘贴 `trackView()`, (中文(简体) ), `trackClick()`, (中文(简体) ), `trackHover()`, (中文(简体) ), `trackFlagView()` | 没有 | 这些调用释放出 Insights API 事件 | 这个 [节点 SDK 集成指南](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html) 覆盖请求的上下文、配置持续性、内容输入分辨率以及混合节点+浏览器 设置细节. ## 利用发展 软件包本地 Dev 牵引装置来自 `packages/node/node-sdk/dev/` 读取 `.env` 从此 软件包目录. 1. 从 `.env.example` 创建或更新 `packages/node/node-sdk/.env`。 。 。 . 2. 优先重现标准 `PUBLIC_...` 变量名称显示于 `.env.example`。 。 。 . 3. 从 repo 根开始拉带 : ```sh pnpm --filter @contentful/optimization-node dev ``` ## 相关 - [将优化节点SDK整合到节点应用中](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-node-sdk-in-a-node-app.html) - 说吧 逐步服务器侧集成指南 - [节点 SDK 生成引用](https://contentful.github.io/optimization/modules/_contentful_optimization-node.html) - 说吧 导出 API 引用 - [节点参考执行](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/implementations/node-sdk/README.md) - 服务器交付 使用请求范围 SDK 调用执行 - [节点+ 网络参考实施](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/implementations/node-sdk+web-sdk/README.md) - 说吧 安全部门改革和浏览器混合执行 - [优化 Web SDK](https://github.com/contentful/optimization/blob/optimization-node-v2.2.1/packages/web/web-sdk/README.md) - 同一应用程序时使用的浏览器 SDK 还需要客户方的同意、持久性、跟踪或实时更新 ## 常见问题 ### @contentful/optimization-node 是什么？ 内容优化节点\.js SDK ### 如何安装 @contentful/optimization-node？ 在项目目录运行 npm install @contentful/optimization-node，或使用 pnpm add / yarn add / bun add。 ### @contentful/optimization-node 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @contentful/optimization-node 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @contentful/optimization-node 可以商用吗？ @contentful/optimization-node 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @contentful/optimization-node 的下载量有多少？ 根据 npm 官方下载统计，@contentful/optimization-node 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,691 次，日均约 123 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @contentful/optimization-node 还在维护吗？ 最新版本 2\.2\.1 发布于 2026/11/06（4 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/02/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。