# @dotcms/experiments 中文文档

规范地址：https://npmcn.com/package/%40dotcms/experiments/

版本：26\.11\.17-1
npm 元数据更新时间：2026-11-17T15:13:08.619Z
中文译文更新时间：2026-11-17T17:23:35.827Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dotcms/experiments
原文对照：https://npmcn.com/package/%40dotcms/experiments/?lang=original
项目主页：https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/experiments/README.md
源码仓库：https://github.com/dotCMS/core#main

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：307 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18，react-dom \>=18，@dotcms/uve 26\.11\.17-1，@dotcms/react 26\.11\.17-1，@dotcms/types 26\.11\.17-1，@dotcms/client 26\.11\.17-1
- 首次发布：2024-04-12T19:24:33.284Z
- 最新版本发布：2026-11-17T15:13:08.405Z
- 近 30 天下载量：5049（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：335（近 12 个月 193 个）

## 中文简介

官方JavaScript库使用实验与DotCMS.

## 安装

```sh
npm install @dotcms/experiments
```

也可以使用：`pnpm add @dotcms/experiments`、`yarn add @dotcms/experiments`、`bun add @dotcms/experiments`

## README

# 点CMS 实验 SDK

这个 `@dotcms/experiments` SDK是官方的dotCMS JavaScript库,帮助在您的网络应用程序中添加A/B测试. 它处理一个页面的不同变体的用户任务,并跟踪其相互作用.

## 概览

### 何时使用

-   在您的网络应用程序中添加 A/B 测试能力
-   运行实验以优化用户体验
-   对真实用户测试不同的页面变体
-   用 DotCMS 分析跟踪实验性能

### 关键特性

-   **用户指定给实验**: 自动指派用户到不同的实验变体,确保不同的用户体验和可靠的测试数据
-   **重定向的链接验证**:检查链接以确保用户被重定向到指定的实验变体,保持测试过程的完整性
-   **自动查看事件发送**: 自动将 PageView 事件发送给 DotCMS 分析器, 从而能够实时跟踪用户参与和实验效果

## 目录

-   [概览](https://npmcn.com/package/%40dotcms/experiments/#readme-overview)
-   [安装](https://npmcn.com/package/%40dotcms/experiments/#readme-installation)
-   [我该用哪个SDK版本?](https://npmcn.com/package/%40dotcms/experiments/#readme-which-sdk-version-should-i-use)
-   [开始](https://npmcn.com/package/%40dotcms/experiments/#readme-getting-started)
    -   [公共 API](https://npmcn.com/package/%40dotcms/experiments/#readme-public-api)
    -   [实验HOC](https://npmcn.com/package/%40dotcms/experiments/#readme-withexperiments-higher-order-component)
    -   [配置对象](https://npmcn.com/package/%40dotcms/experiments/#readme-configuration-object)
-   [使用量](https://npmcn.com/package/%40dotcms/experiments/#readme-usage)
    -   [用 @ dotcms/ react( 建议)](https://npmcn.com/package/%40dotcms/experiments/#readme-with-dotcmsreact-recommended)
    -   [Next.js App路由器](https://npmcn.com/package/%40dotcms/experiments/#readme-nextjs-app-router)
    -   [配置最佳做法](https://npmcn.com/package/%40dotcms/experiments/#readme-configuration-best-practices)
    -   [反间谍](https://npmcn.com/package/%40dotcms/experiments/#readme-anti-patterns)
    -   [如何运作](https://npmcn.com/package/%40dotcms/experiments/#readme-how-it-works)
-   [解决问题](https://npmcn.com/package/%40dotcms/experiments/#readme-troubleshooting)
-   [支助](https://npmcn.com/package/%40dotcms/experiments/#readme-support)
-   [捐款](https://npmcn.com/package/%40dotcms/experiments/#readme-contributing)
-   [许可证发放](https://npmcn.com/package/%40dotcms/experiments/#readme-licensing)

## 安装

通过 npm 安装软件包 :

```bash
npm install @dotcms/experiments
```

或用雅兰:

```bash
yarn add @dotcms/experiments
```

## 我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 `@dotcms/*` 货包船 地点 **完全相同的版本编号** 作为点CMS的发布,它是为(例如:点CMS)而建的 `26.7.14-1` → `@dotcms/client@26.7.14-1`, (中文(简体) ), `@dotcms/react@26.7.14-1`,等等).

**简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.**

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的东西,所以一个更老的SDK通常会继续工作 对一个新的点CMS案例,罚款。 但偶尔,释放确实包括一个真正的 打破更改——如果您的 SDK 年龄超过此点, 它会停止正确工作 .

你不需要自己去跟踪它: 你的点CMS实例总是知道最古老的SDK 版本它仍然支持,SDK自动对照它检查自己. 狦琌 使用SDK这个太老了,你会看到一个清晰的警告 在你的控制台上告诉你 升级.

**建议:** 将您的 SDK 与您的点CMS 实例相同的版本连接, 并且只接通 当您升级了点CMS, 或者当控制台告诉你.

> **在LTS发布?** LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.
> 
> 想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 [发布和支持生命周期( S)](https://dev.dotcms.com/docs/release-support-lifecycle)。 。 。 .

## 开始

### 公共 API

软件包导出 **一个** 公共符号 :

| 导出 | 说明 |
| --- | --- |
| `withExperiments` | 包装布局组件的 HOC( 通常为 `DotCMSLayoutBody`实验处理 |

`DotExperimentsProvider` 其他内部因素有: **没有** 部分为公共API. 不要导入它们—— `withExperiments` 内接供养.

### `withExperiments` 上级部分

`withExperiments` 用实验功能将您的页面组件包起来 :

-   给实验变体分配用户任务
-   自动重定向到正确的变体
-   防止内容在变异装入时闪烁
-   自动页面视图跟踪到 dotCMS 分析
-   点击事件处理以保持整个导航的变体一致性

> **重要内容:** `withExperiments` 内部使用反应钩. 必须叫它 **无条件** 在使用它的部件的每个成像上。 见 [反间谍](https://npmcn.com/package/%40dotcms/experiments/#readme-anti-patterns)。 。 。 .

### 配置对象

这个 `config` 对象传递到 `withExperiments` 接受下列属性:

| 财产 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | 对 | —— 说 | jsKey from the dotCMS Analytics / Experiments app(前端密钥,不是m2m) 的相接键 |
| `server` | 对 | —— 说 | 点CMS **来源** URL(例如:. `https://your-dotcms-instance.com`(-不是一个CDN) |
| `redirectFn` | 没有 | `window.location.replace` | SPA重定向函数(如:. `router.replace` 在下一个.js中) |
| `trackPageView` | 没有 | `true` | 启用/ 禁用自动页面视图跟踪 |
| `debug` | 没有 | `false` | 浏览器控制台的 Verbose 记录 |

## 使用量

### 用 @ dotcms/ react( 建议)

使用 **单独视图或路径** 有实验和没有实验的页。 这样可以避免呼叫 `withExperiments` 有条件地在同一部分.

```tsx
// views/StandardPage.tsx — no experiments
"use client";

import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";

import { pageComponents } from "@/components/content-types";

export function StandardPage({ pageContent }) {
    const { pageAsset } = useEditableDotCMSPage(pageContent);

    return (
        <main>
            <DotCMSLayoutBody page={pageAsset} components={pageComponents} />
        </main>
    );
}
```

```tsx
// views/ExperimentsPage.tsx — experiments always enabled on this view
"use client";

import { withExperiments } from "@dotcms/experiments";
import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";
import { useRouter } from "next/navigation";

import { pageComponents } from "@/components/content-types";

export function ExperimentsPage({ pageContent }) {
    const { pageAsset } = useEditableDotCMSPage(pageContent);
    const { replace } = useRouter();

    const LayoutBody = withExperiments(DotCMSLayoutBody, {
        apiKey: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_KEY!,
        server: process.env.NEXT_PUBLIC_DOTCMS_HOST!,
        redirectFn: replace,
        debug: process.env.NEXT_PUBLIC_DOTCMS_DEBUG === "true",
    });

    return (
        <main>
            <LayoutBody page={pageAsset} components={pageComponents} />
        </main>
    );
}
```

在 App 路由器中将每个视图连接到自己的路线( 例如) `/blog` 用于实验,标准页的全集).

> **学习更多关于 `DotCMSLayoutBody`**: 见 [@ dotcms/ react SDK 文档](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/react/README.md#dotcmslayoutbody)。 。 。 .

### Next.js App路由器

实例: [`examples/nextjs-analytics-experiments`](https://npmcn.com/examples/nextjs-analytics-experiments)

该项目表明:

-   所有路线的分析 `@dotcms/analytics` 内 `layout.tsx`
-   实验 `/blog` 通过 `withExperiments` 在专用视图中
-   在UVE避免违反规则的安全隔离

**环境变量** (见实例) `.env.local.example`:

```bash
NEXT_PUBLIC_DOTCMS_HOST=http://localhost:8080      # dotCMS origin — NOT a CDN
NEXT_PUBLIC_DOTCMS_ANALYTICS_KEY=                  # jsKey (frontend key)
NEXT_PUBLIC_DOTCMS_DEBUG=true
```

**核查** (DevTools 网络):

1.  在试验路线上: `POST {HOST}/api/v1/experiments/isUserIncluded`
2.  与 `debug: true`数字 : `[dotCMS ...]` 控制台中的日志
3.  在 UVE 中打开页面 — 没有“ 客户端例外” 覆盖

### 配置最佳做法

-   **使用环境变量** 页:1 `apiKey` 财务报告和审定财务报表 `server`
-   **专用路线/景点** 用于实验页面——不要切换 `withExperiments` 上面有一个三角星 `apiKey` 在同一个部分
-   **框架路由器**: 通过 `router.replace` (下个js)或等同于 `redirectFn` 用于SPA 导航
-   **来源 URL**数字 : `server` 必须指向点CMS实例源。 不要使用 Azure Front Door, CloudFront, 或其他 CDNs —— 实验 API 响应是会话特定的, 并且不能被缓存在边缘
-   **对齐的 SDK 版本**: 保留 `@dotcms/client`, (中文(简体) ), `@dotcms/react`, (中文(简体) ), `@dotcms/uve`, (中文(简体) ), `@dotcms/types`,以及 `@dotcms/experiments` 在同一版本线上
-   **调试模式**: 使开发期间能够解决任务问题

### 反间谍

执行 **没有** 使用这些模式——它们可以崩溃 Next.js App Router 页面和 UVE 编辑器:

```tsx
// ❌ Conditional withExperiments — violates rules of hooks
const Layout = experimentConfig.apiKey
    ? withExperiments(DotCMSLayoutBody, config)
    : DotCMSLayoutBody;

// ❌ Early return before withExperiments in the same component
if (!apiKey) return <DotCMSLayoutBody {...props} />;
const Layout = withExperiments(DotCMSLayoutBody, config);

// ❌ Importing internal provider
import { DotExperimentsProvider } from "@dotcms/experiments";

// ❌ CDN as server
server: "https://cdn.example.com"
```

使用单独的组件/路由(参见 [用 @ dotcms/ 反应](https://npmcn.com/package/%40dotcms/experiments/#readme-with-dotcmsreact-recommended)) (中文(简体) ).

### 如何运作

一旦你包装你的组件 `withExperiments`,SDK自动处理:

1.  **用户指定**: 用户访问有活性实验的页面时指定实验变体
2.  **自动重定向**: 将用户重定向到指定变量 URL( 防止看到错误的变量)
3.  **防闪烁**: 重定向时隐藏内容,以避免立即显示错误的变体
4.  **导航处理**: 用户点击链接时保持变体一致性
5.  **分析跟踪**: 将页面视图事件自动发送到 DotCMS 分析器

**学习更多**数字 : [DotCMS A/B 测试实验](https://www.dotcms.com/product/ab-testing-experiments)

## 解决问题

| 症状 | 可能的原因是 | 怎么办 |
| --- | --- | --- |
| UVE 崩溃: “ 发生了客户端例外 ” | `withExperiments` 或者在UVE状态准备好之前进行初始化实验 | 使用专门的实验视图; 从不使用 `apiKey ? withExperiments(...) : DotCMSLayoutBody` |
| `GET /api/v1/experiments/DEFAULT` 404 (韩语) | 已知后台问题-变体名 `"DEFAULT"` 以实验身份通过 | 无头应用程序无害; 后台另跟踪 |
| "没有指派给客户的实验" | 不在试验中 `Running` 状态,或尚未分析 | 确认点CMS中的实验状态; 校验 `apiKey` 财务报告和审定财务报表 `server` |
| 没有 `isUserIncluded` 请求 | 失踪 `apiKey`,错误的路径,或未挂载的实验视图 | 请检查env vars; 确认页面使用实验视图 |
| 事件到错误的主机 | `server` 指向 CDN 而不是点CMS 来源 | 设定 `server` 到点CMS实例 URL |

## 支助

-   **GitHub 问题**数字 : [打开一个问题](https://github.com/dotCMS/core/issues/new/choose)
-   **社区论坛**数字 : [社区. dotcms.com](https://community.dotcms.com/)
-   **叠叠流**标签 `dotcms-experiments`
-   **企业支助**数字 : [点CMS 支持](https://www.dotcms.com/support)

在报告问题时,包括SDK版本,框架版本,最小复制步骤,以及预期对实际行为.

## 捐款

1.  叉头 [点/核心](https://github.com/dotCMS/core)
2.  创建特性分支
3.  提交更改
4.  打开拉请求

请确保您的代码遵循现有的样式并包含适当的测试 .

在接受任何拉动请求之前,一个自动工具会请您同意 [dotCMS 贡献者协议](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3)。 。 。 .

## 许可证发放

点CMS 可在 [业务来源许可证1.1(BSL)](https://www.dotcms.com/bsl) 或商业执照.

在BSL下,DotCMS可以免费由个人开发商,小企业或机构在总资金中低于5M美元,也可以由非生产环境下的更大型组织使用. BSL每次发布都会在其发布后四年自动转换为GPL v3. 全文和问题,访问 [dotcms.com/bsl (英语)](https://www.dotcms.com/bsl) 财务报告和审定财务报表 [dotcms.com/bsl-faq (英语)](https://www.dotcms.com/bsl-faq)。 。 。 .

大型组织的生产用途,以及管理下的云、服务级协议、支助和企业能力,均根据点集管理系统的商业许可证提供。 关于商业计划、特点和支助选项的详情,见 [dotcms.com/定价](https://www.dotcms.com/pricing)。 。 。 .

## 常见问题

### @dotcms/experiments 是什么？

官方JavaScript库使用实验与DotCMS\.

### 如何安装 @dotcms/experiments？

在项目目录运行 npm install @dotcms/experiments，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）、@dotcms/uve（26\.11\.17-1）、@dotcms/react（26\.11\.17-1）、@dotcms/types（26\.11\.17-1）、@dotcms/client（26\.11\.17-1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dotcms/experiments 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dotcms/experiments 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dotcms/experiments 可以商用吗？

@dotcms/experiments 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcms/experiments 的下载量有多少？

根据 npm 官方下载统计，@dotcms/experiments 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,049 次，日均约 168 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dotcms/experiments 还在维护吗？

最新版本 26\.11\.17-1 发布于 2026/11/17（今天）；至今共发布 335 个版本，其中过去 12 个月发布了 193 个；首次发布于 2024/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

