# @clickmax/rsbuild-plugin 中文文档

规范地址：https://npmcn.com/package/%40clickmax/rsbuild-plugin/

版本：1\.0\.0
npm 元数据更新时间：2026-11-06T00:38:10.387Z
中文译文更新时间：2026-11-10T01:33:48.755Z
软件包许可：GPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40clickmax/rsbuild-plugin
原文对照：https://npmcn.com/package/%40clickmax/rsbuild-plugin/?lang=original
项目主页：https://clickmax.io/

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

- 包体积（解压后）：160 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react \>=19\.0\.0，react-dom \>=19\.0\.0，tailwindcss ^4\.0\.0，@rsbuild/core ^2\.2\.0，@tanstack/react-start \>=1\.168\.60 \<2，@tanstack/react-router \>=1\.170\.41 \<2
- 首次发布：2026-10-02T15:32:15.656Z
- 最新版本发布：2026-11-06T00:38:10.225Z
- 近 30 天下载量：4902（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

点击max平台集成 Rsbuilding: React,Tailwind CSS和TanStack Start 以静态预降,被打包入可出版站点文物.

## 安装

```sh
npm install @clickmax/rsbuild-plugin
```

也可以使用：`pnpm add @clickmax/rsbuild-plugin`、`yarn add @clickmax/rsbuild-plugin`、`bun add @clickmax/rsbuild-plugin`

## README

# @ 点击max/ rsbuilding- plugin

在 Clickmax 上建立网站的设置 。 一个插件配置 [建设](https://rsbuild.rs/) 与回放 19, 尾风 CSS 4和 [TanStack 启动](https://tanstack.com/start),使每个页面在构建时间为静态的 HTML,并将结果包成 Clickmax 可以发布.

您不需要自己配置 React, Tailwind, 路由或输出路径 。 一个 Clickmax 网站的整个配置是:

```ts
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { clickmax } from '@clickmax/rsbuild-plugin'

export default defineConfig({ plugins: [clickmax()] })
```

```bash
rsbuild dev     # local development with hot reload
rsbuild build   # production build: dist/client, dist/server and the publishable dist/clickmax/
```

与软件包匹配的 TypeScript 设置船; 一个站点 `tsconfig.json` 只需要自己的列表和导入别名 :

```json
{
  "extends": "@clickmax/rsbuild-plugin/tsconfig",
  "include": ["**/*.ts", "**/*.tsx"],
  "compilerOptions": { "paths": { "#/*": ["./src/*"] } }
}
```

## 网站的结构

| 路径 | 目的 |
| --- | --- |
| `src/routes/` | 文件路线. `index.tsx` 实值 `/`, (中文(简体) ), `about/team.tsx` 实值 `/about/team`, (中文(简体) ), `_layout.tsx` 在不添加 URL 片段的情况下将孩子包裹, `posts/$slug.tsx` 是一条动态路线. |
| `src/routes/__root.tsx` | HTML 文档 shell (`<html>`, (中文(简体) ), `<head>`, (中文(简体) ), `<body>`) (中文(简体) ). |
| `src/styles.css` | 全局样式表,导入于 `?url` 从根道. 风道设施在各地都有 `src/`。 。 。 . |
| `public/` | 文件逐字复制到站点根:图像、字体、, `robots.txt`,可下载文档。 以绝对路径参考,例如 `/images/logo.png` (前缀为 `basePath` 当站点未挂起时 `/`) (中文(简体) ). |
| `src/assets/` (或以下任何地方) `src/`(中文(简体) ) | 从代码导入的图像和其他文件. 他们的名下藏有大麻 永远藏起来. |

新路线自动取出; 运行 `rsbuild build` (或保留 `rsbuild dev` 运行)以重生路径树.

## 什麽 `rsbuild build` 担保

网站作为静态文件发布;运行时没有服务器. 该建筑强制执行:

-   每一个有组件且没有路径参数的路由都会向 `<route>/index.html`. 动态路线(`$slug`) 仅用于您列出的路径 `prerender.paths`。 。 。 .
-   页面之间的链接( E)`<a href>`页:1 链接到其他网站和文件 `public/` 独自一人.
-   每个图像,样式表,脚本,字体或文档都存在由同一站点的URL提供的页面引用. 缺少的文件会以页面和引用它的 URL 失败构建 .
-   无法制取的路由( 例如投放加载器) 失败 。 没有部分公布.
-   数据可以在路由内获取 `loader` 与 `fetch` 从公共API。 装入器在构建时运行,以便在客户端导航时再次在浏览器中渲染页面,所以它们不得使用节点专用API等 `fs`。 。 。 . **服务器功能( E)`createServerFn`)和服务器路由处理器不支持**: 网站启用后没有服务器 。 使用服务器功能的客户端代码,以及链接到API路由的页面,会以所涉及的文件或URL来失败构建.
-   没有发布服务器代码 . `dist/server/` 仅用于在构建过程中渲染页面.

公布的产出列于 `dist/clickmax/manifest.json` (路线,文件,大小和散列). `dist/clickmax/site.tar.gz` 是 Clickmax 接收的归档 .

## 使控制可以发现

漏斗列出每个已公布的路由, 从路由的最后 HTML 读入 `dist/clickmax/manifest.json`。只有以 Clickmax 运行时组件标记的元素数:每个 写入 `data-cx-component` 财务报告和审定财务报表 `data-cx-entity-id` ,并记录 其 DOM 识别码下的元素。 自定义触发器被宣告为 `CxTrigger` 从 `@clickmax/rsbuild-plugin/runtime/core`数字 :

```tsx
import { CxTrigger, useCxTrigger } from '@clickmax/rsbuild-plugin/runtime/core'

<CxTrigger id="read-70" label="Read 70% of the page" />

// In the site's own code, when the condition is met:
const fire = useCxTrigger('read-70')
fire()
```

仅通过浏览器的事件 `ClickmaxProvider`,在绕行的根道上做了一次 `<Outlet />` (点击max站点模板已经这样做了). 没有它, `CxTrigger` 列在 表面的,绝不然.

| `data-cx-component` | 列为 |
| --- | --- |
| `button` | 按钮点击 |
| `link` | 链接点击 |
| `visible` | 元素可见度 |
| `lead-form`, (中文(简体) ), `form` | 提交表格和联系方式 |
| `trigger` (单位:千美元)`CxTrigger`(中文(简体) ) | 自定义触发, 以其命名 `label` |

规则构建执行, 中断时与路径和元素失败 :

-   每个标记元素都有 `id` 无空白、控制字符或 逗号,在所提供的文档中独一无二。 同一ID可能在不同的路线上被再用. 明确通过 ID; 永远不要用它生成 `useId()`,在建构之间变化.
-   A 类 `CxTrigger` 标签最多有255个字符,没有换行符。 漏斗显示是...
-   一个元素带有运行时标记或浏览器SDK注释,从未两者兼有.
-   未知 `data-cx-component` 值失败;不要用手写属性.

预交时的渲染标记元素:仅客户模式和计算元素不在 HTML 构建读取。 使用 `aria-label` 或者说 `title` ;否则,该构建将使用 可见文本、名称、输入值或ID。 检查嵌入和 Vturb 播放器记录为 集成发现,不能证明购买或视频活动支持.

浏览器 SDK 注释 (`data-cx-track`, (中文(简体) ), `form[data-cx-ingest-form]`, (中文(简体) ), `cm-*` 继续工作 在浏览器中,但没有列出漏斗。 建筑指纹 `capability warning legacy_selector` 和每个找到的路线和身份证.

## 已出版页面之间的导航

使用普通的 TanStack 软件 `Link`, (中文(简体) ), `Navigate`, (中文(简体) ), `useNavigate()` 财务报告和审定财务报表 `router.navigate()` 电话,或本地 锚. 该网站拥有其目的地. 漏斗箭头手动代表漏斗,永远不要 重写按钮,链接,形成或退出导航.

插件自动观察您已有的路由器返回的路由器 `getRouter` 工厂何时 已发布的浏览器 SDK 已激活。 没有跟踪帮助器、动作包或路由器注册 应用程序来源中的要求。 水合客户端导航和预先直接输入这两种工作; 不强制重新装入文档进行跟踪.

## 选项

所有选项都是可选的。 默认匹配 Clickmax 站点模板 .

```ts
clickmax({
  srcDirectory: 'src',            // where the application code lives
  basePath: '/',                  // mount path of the site, e.g. '/landing' for a sub-path deployment
  prerender: {
    paths: ['/posts/hello'],      // concrete paths to render for dynamic routes such as /posts/$slug
    crawlLinks: true,             // follow same-site links in rendered pages
    concurrency: 4,               // pages rendered in parallel
  },
  plugins: [],                    // extra Rsbuild plugins, registered after the platform ones
  limits: {                       // local packaging limits; the platform enforces its own
    maxFiles: 20_000,
    maxFileBytes: 100 * 1024 * 1024,
    maxTotalBytes: 1024 * 1024 * 1024,
  },
})
```

`basePath` 还设置了路由器basepath和资产 URL 前缀. 公共档案也在其中提供: `basePath: '/landing'`,文档 `public/images/logo.png` 实值 `/landing/images/logo.png`,并提及 `/images/logo.png` 因为它会404号一旦部署。 链接( E)`<a href>`)到外出路径 `basePath` (c) 被作为同一宿主上的另一站点对待,没有被跟踪.

### 你能够和不能控制的东西 `rsbuild.config.ts`

其它 `defineConfig` 键( 例如 `source.alias`, (中文(简体) ), `source.define` 对于常客, `tools.rspack`)照常工作. 下面的密钥为平台所拥有; 设置它们失败的构建, 并有信件命名密钥 :

| 密钥 | 原因 |
| --- | --- |
| `output.distPath`, (中文(简体) ), `environments.*.output.distPath` | 平台读取 `dist/client` 财务报告和审定财务报表 `dist/server` |
| `output.assetPrefix`, (中文(简体) ), `server.base` | 使用 `basePath` |
| `server.publicDir` | 公开文件总是来自 `./public` |
| `output.cleanDistPath: false` | 将公布 Stale 文件 |
| `source.define` 提及 `CLICKMAX_PUBLISH*` 或者说 `process.env` | 证书永远不能到达浏览器捆绑 |

## 环境

插件读取这些变量 。 您通常不会自己设置; 点击max 平台运行您的构建时会设置 .

| 变量 | 效果 |
| --- | --- |
| `CLICKMAX_SANDBOX=1` | Clickmax 沙盒内部的开发: dev 服务器在端口上听 `10143` 并允许编辑器预览集成. |
| `MXD_STUDIO_ORIGIN_SUFFIXES` | Clickmax 源代码可驱动编辑器预览 。 由站台设置. |
| `CLICKMAX_SKIP_VERSION_CHECK=1` | 跳过 npm 上的最新插件版本的一次/ 构建搜索( 当新版本存在时会打印出警告; 构建永远不会依赖于它) . |
| `CLICKMAX_BASE_PATH` | 覆盖作者所挂载的生产架构,包括路由器和资产 URL 。 使用 `basePath` 发展选择. |
| `CLICKMAX_PUBLISH_SOURCE_IDENTITY` | 可选平台提供源指纹绑入出版物再试. |
| `CLICKMAX_PUBLISH_ATTEMPT_ID`, (中文(简体) ), `CLICKMAX_PUBLISH_TOKEN`, (中文(简体) ), `CLICKMAX_PUBLISH_API_URL` | 仅存在于一个建筑中,该平台将运行发布。 包装后, 块上传 `site.tar.gz`;成功意味着平台接受了它进行处理. 三者须相会相会,而只为相会相会相会相会 `rsbuild build`。 。 。 . |

没有公布的变量,除了上面的版本搜索之外,一个构建没有网络 I/O 。 证书只在节点构建过程中被读取,从未被写入输出.

## 在不重建的情况下重试上传

如果一个建筑成功但上传失败, 文物将留在 `dist/clickmax/`具有新的环境证书:

```ts
import { publishArtifact } from '@clickmax/rsbuild-plugin'

await publishArtifact() // verifies dist/clickmax/ against the build's own record, then uploads
```

重用原始尝试、挂载和准备字节 。 允许更新该标志; 修改约束要求进行新的出版尝试。 不要重运行出版物构建到 重试一个上传. `dist/clickmax/status.json` 记录本地进度; 接受不是证明 现场直播.

## 错误

插件所抛出的所有错误都有一个稳定 `code` 以及一个写着要改变的信息:

-   `ClickmaxConfigError`: 配置冲突,在编译前提出.
-   `ClickmaxArtifactError`:构建输出不能成为完整的站点(缺少引用,服务器功能,不安全文件).
-   `ClickmaxPublishError`: 上传失败; `stage` 说在哪里(`env`, (中文(简体) ), `prepare`, (中文(简体) ), `upload`, (中文(简体) ), `complete`和 `retryable` 以后再试有没有道理.

## 支持的工具链

-   节点js 24.16或更新
-   `@rsbuild/core` ^2.2
-   `@tanstack/react-start` 1.168.60 或较新的(1.x)
-   反应 19, 尾风 CSS 4

## 许可证

仅限GPL-3.0. 见 [自由主义](https://npmcn.com/package/%40clickmax/rsbuild-plugin/LICENSE)。 。 。 .

## 常见问题

### @clickmax/rsbuild-plugin 是什么？

点击max平台集成 Rsbuilding: React,Tailwind CSS和TanStack Start 以静态预降,被打包入可出版站点文物\.

### 如何安装 @clickmax/rsbuild-plugin？

在项目目录运行 npm install @clickmax/rsbuild-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）、react-dom（\>=19\.0\.0）、tailwindcss（^4\.0\.0）、@rsbuild/core（^2\.2\.0）、@tanstack/react-start（\>=1\.168\.60 \<2）、@tanstack/react-router（\>=1\.170\.41 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clickmax/rsbuild-plugin 支持 TypeScript 吗？

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

### @clickmax/rsbuild-plugin 支持 ESM 还是 CommonJS？

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

### @clickmax/rsbuild-plugin 可以商用吗？

@clickmax/rsbuild-plugin 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @clickmax/rsbuild-plugin 的下载量有多少？

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

### @clickmax/rsbuild-plugin 还在维护吗？

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