# @builder\.io/sdk-react 中文文档

规范地址：https://npmcn.com/package/%40builder.io/sdk-react/

版本：5\.4\.2
npm 元数据更新时间：2026-10-20T12:03:17.835Z
中文译文更新时间：2026-11-08T19:00:54.340Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40builder.io/sdk-react
原文对照：https://npmcn.com/package/%40builder.io/sdk-react/?lang=original
项目主页：https://github.com/BuilderIO/builder/tree/main/packages/sdks/output/react
源码仓库：https://github.com/BuilderIO/builder

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

- 包体积（解压后）：1.2 MB，334 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16 \|\| ^19\.0\.0-rc
- 首次发布：2022-08-15T20:38:20.953Z
- 最新版本发布：2026-10-20T12:03:17.419Z
- 近 30 天下载量：128062（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：236（近 12 个月 42 个）

## 中文简介

创建器.io SDK 用于反应

## 安装

```sh
npm install @builder.io/sdk-react
```

也可以使用：`pnpm add @builder.io/sdk-react`、`yarn add @builder.io/sdk-react`、`bun add @builder.io/sdk-react`

## README

# Builder.io 反应 SDK v2

这是反应V2 SDK, `@builder.io/sdk-react`它是对SDK的完全改写,并具有以下好处:

-   零客户端依赖性
-   大小小得多( 25kb)

注:如果在无服务器环境(如下个或氢)上部署的网络app中使用SDK,则可能需要从中导入SDK `@builder.io/sdk-react/edge`。这是处理围绕无服务器环境的边缘大小写的特殊导入.

## 最低限度支持的版本

这个 [`peerDependencies`](https://npmcn.com/package/%40builder.io/sdk-react/package.json) 许可 **反应 QQ16** (和回放19发布候选. 这是一个安装范围,而不是对反应16的积极支持的保证;参见 [框架版本矩阵](https://npmcn.com/package/README.md#framework-version-guidance)。 。 。 .

## API 参考

要使用SDK,你必须:

-   使用 `fetchOneEntry`: 您可以在这里看到如何使用它 [https://www.builder.io/c/docs/content-api (中文(简体) )](https://www.builder.io/c/docs/content-api),它如何区别于反应 V1 SDK's `builder.get()` 函数.
    
-   将数据传递给 `Content` 组件。 以下是一个简化的例子,显示您将如何同时使用:
    

```tsx
import { Content, fetchOneEntry, isPreviewing } from '@builder.io/sdk-react';
import { useEffect, useState } from 'react';

const BUILDER_PUBLIC_API_KEY = 'YOUR API KEY';

function App() {
  const [content, setContent] = useState(undefined);

  useEffect(() => {
    fetchOneEntry({
      model: 'page',
      apiKey: BUILDER_PUBLIC_API_KEY,
      userAttributes: {
        urlPath: window.location.pathname || '/',
      },
    }).then((content) => {
      setContent(content);
    });
  }, []);

  const shouldRenderBuilderContent = content || isPreviewing();

  return shouldRenderBuilderContent ? (
    <Content content={content} model="page" apiKey={BUILDER_PUBLIC_API_KEY} />
  ) : (
    <div>Content Not Found</div>
  );
}
```

看这个 [实例](https://npmcn.com/package/%40builder.io/sdk-react/#readme-examples) 更多信息.

### 多个 `Content` 一个页面上的组件

每个 `Content` 包含一个可变容器或A/B测试的,其中插入了这些功能所需的帮助脚本的副本。 如果一个页面为数 `Content` 组件(例如页眉、页体和页脚),将其打包一次 `BuilderScripts` 援助者们只被派遣一次

```tsx
import { BuilderScripts, Content } from '@builder.io/sdk-react';

export default function Layout({ children }) {
  return <BuilderScripts nonce={cspNonce}>{children}</BuilderScripts>;
}
```

使用一个 `BuilderScripts` 上层 `Content` 使用这些特性,而不是每个周围一个 `Content`兄弟姐妹的包装纸 每人发一份 A 类 `BuilderScripts` 在另一棵树上筑巢 却一无所出 所以在树上再多放一棵 这个 `nonce` 道具是可选的,只有内容安全政策需要. `BuilderScripts` 总是释放帮助者,即使里面没有东西使用个性化或A/B测试,所以只将其放置在做测试的页面上.

#### Next.js App路由器

不要进口 `BuilderScripts` 从 `@builder.io/sdk-react` 直接在服务器组件中, 例如 `app/layout.tsx`。下一个.js在浏览器中为它加载不同的SDK构件,而不是您的 `"use client"` 构成部分用途 `Content`这样 `Content` 不能看到包装。 服务器 HTML 有一条帮助脚本, 浏览器为每条 `Content`,水合失败.

从客户端文件中再导出并导入:

```tsx
// components/builder-scripts.tsx
'use client';
export { BuilderScripts } from '@builder.io/sdk-react';
```

```tsx
// app/layout.tsx
import { BuilderScripts } from '../components/builder-scripts';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BuilderScripts>{children}</BuilderScripts>
      </body>
    </html>
  );
}
```

包装 `Content` 同一客户端组件内的组件也起作用.

## 微缩

此 SDK 是由 [微缩](https://github.com/BuilderIO/mitosis)。要看到Mitosis源代码,请去 [这里](https://npmcn.com/package/)。 。 。 .

## 特性支持

看SDK的状态 [这些表格](https://npmcn.com/package/README.md#feature-implementation)。 。 。 .

## 开始

```
npm install @builder.io/sdk-react
```

## 实例

-   [反应 + Vite](https://npmcn.com/examples/react-v2/)
-   [Next.js App路由器](https://npmcn.com/examples/nextjs-app-dir-v2/)
-   [Next.js 页面路由器](https://npmcn.com/examples/nextjs-pages-dir-v2/)

## 获取

此套件使用抓取 。 见 [这些文件](https://github.com/BuilderIO/this-package-uses-fetch/blob/main/README.md) 更多信息.

## 常见问题

### @builder\.io/sdk-react 是什么？

创建器\.io SDK 用于反应

### 如何安装 @builder\.io/sdk-react？

在项目目录运行 npm install @builder\.io/sdk-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16 \|\| ^19\.0\.0-rc）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @builder\.io/sdk-react 支持 TypeScript 吗？

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

### @builder\.io/sdk-react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @builder\.io/sdk-react 可以商用吗？

@builder\.io/sdk-react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @builder\.io/sdk-react 的下载量有多少？

根据 npm 官方下载统计，@builder\.io/sdk-react 在 2026/10/09 – 2026/11/07 这 30 天内被下载 128,062 次，日均约 4,269 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @builder\.io/sdk-react 还在维护吗？

最新版本 5\.4\.2 发布于 2026/10/20（19 天前）；至今共发布 236 个版本，其中过去 12 个月发布了 42 个；首次发布于 2022/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。