# @cloudflare/kumo 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/kumo/

版本：2\.18\.0
npm 元数据更新时间：2026-11-09T16:18:06.702Z
中文译文更新时间：2026-11-10T02:57:58.908Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/kumo
原文对照：https://npmcn.com/package/%40cloudflare/kumo/?lang=original
源码仓库：https://github.com/cloudflare/kumo

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

- 包体积（解压后）：7.7 MB，568 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：zod ^4\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，echarts ^6\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@phosphor-icons/react ^2\.1\.10
- 首次发布：2026-02-03T19:22:28.943Z
- 最新版本发布：2026-11-09T16:18:06.312Z
- 近 30 天下载量：2328365（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

Kumo - Cloudflare用于构建现代网络应用程序的组件库

## 安装

```sh
npm install @cloudflare/kumo
```

也可以使用：`pnpm add @cloudflare/kumo`、`yarn add @cloudflare/kumo`、`bun add @cloudflare/kumo`

## README

# @cloudflare/kumo (英语)

Cloudflare用于构建现代网络应用的组件库.

## 安装

```bash
pnpm add @cloudflare/kumo
```

### 同伴依赖关系

Kumo 需要以下对等关系:

```bash
pnpm add react react-dom @phosphor-icons/react
```

## 构成部分文件

Kumo包括一个内置的CLI

```bash
npx @cloudflare/kumo ls         # List all components
npx @cloudflare/kumo doc Button # Get component documentation
npx @cloudflare/kumo docs       # Get all component docs
```

"CLI"从 `ai/component-registry.json` (由TypeScript类型+演示示例生成).

## 使用量

### 导入组件

```tsx
// Main package import
import { Button, Input, Surface } from "@cloudflare/kumo";

// Granular imports (recommended for tree-shaking)
import { Button } from "@cloudflare/kumo/components/button";
```

### 导入样式

#### 用于 Tailwind CSS 用户

**重要内容:** 尾风 CSS v4 不扫描 `node_modules/` 默认。 您必须添加一个 `@source` 指令使Tailwind能够发现Kumo组件所使用的工具类. 没有此选项, 组件可能会被缺少的样式所渲染( 例如, 未居中对话框) .

在您的主 CSS 文件( 例如 ) 中 . `app.css`:

```css
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";
```

> **进口订单事项** —— 说 `@cloudflare/kumo/styles` 一定要来 **在此之前** `@import "tailwindcss"` 所以库莫 `@theme` 符号先被注册 .

> **说明:** 这个 `@source` 路径相对于您的 CSS 文件 。 根据您的项目结构调整它—— 例如, 如果您的CSS 处于 `src/styles/`你也许需要 `../../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}`。 。 。 .

或者,您可以使用默认样式导出( E)`@cloudflare/kumo/styles`等值为 `styles/tailwind`。 。 。 .

如果你是的话 **没有** 使用 Tailwind CSS, 取而代之使用独立架构(见下文)- 否 `@source` 需要指令.

#### 对于非泰尔风用户( 单独)

```js
import "@cloudflare/kumo/styles/standalone";
```

这导入了完整编译的包含所有 Tailwind 公用设施和 Kumo 风格的 CSS 文件 。 不需要尾风配置!

**独立内容包括:**

-   Kumo 组件使用的所有 Tailwind 工具类
-   Kumo 组件样式
-   暗模式支持( 通过 `data-mode="dark"` 属性)
-   所有动画和键框
-   反应型公用事业

**说明:** 独立的CSS是精密化和优化的,但将大于Tailwind版本,因为它包括所有公用事业.

### 基础 UI 初级

Kumo 捆绑 [基础UI](https://base-ui.com/) 并再出口所有原始物以供高级使用:

```tsx
// Barrel import - imports all primitives (convenient but larger bundle)
import { Popover, Slider, Accordion } from "@cloudflare/kumo/primitives";

// Granular imports - tree-shakeable, smaller bundles (recommended)
import { Popover } from "@cloudflare/kumo/primitives/popover";
import { Slider } from "@cloudflare/kumo/primitives/slider";
import { Accordion } from "@cloudflare/kumo/primitives/accordion";
```

> **说明:** 当有库莫组件时,更倾向于使用它。 初级产品是库莫尚未使用的自定义部件或需要精细控制的情况.
> 
> **性能提示 :** 使用颗粒进口(`@cloudflare/kumo/primitives/{name}`),以更好的树摇和更小的捆绑尺寸.

#### 更新原始内容

初级出口自动由Base UI生成. 升级后 `@base-ui/react`数字 :

```bash
# Regenerate primitive files to sync with new Base UI version
pnpm build:primitives

# Review changes (new/removed primitives)
git diff src/primitives/

# Commit if primitives changed
git add src/primitives/ package.json
git commit -m "chore: update primitives for base-ui@x.x.x"
```

这个 `build:primitives` 脚本 :

-   生成单个原始文件 `src/primitives/*.ts`
-   更新枪管导出于 `src/primitives/index.ts`
-   更新 `package.json` 有颗粒导出路径
-   每次建设之前通过 `prebuild` 脚本

#### 校验构建输出

建成后,验证原始人输出:

```bash
# Run post-build validation (checks dist/ structure)
pnpm validate:build
```

此验证 :

-   所有原始的JS文件都存在于 `dist/primitives/`
-   所有类型定义都存在于 `dist/src/primitives/`
-   碱基UI被捆绑( 不外部化)
-   导入路径引用捆绑模块
-   存在原始地图

## 发展

**关于综合贡献文件,见 [一般事务人员(其他职等)](https://npmcn.com/package/AGENTS.md)。 。 。 .**

### 创建新组件

使用脚手架工具快速创建所有需要的文件和配置的新组件 :

```bash
# Create a new component
pnpm new-component

# Or use the shorthand
pnpm new
```

**它创造了什么:**

-   组件文件 : `src/components/{name}/{name}.tsx`
-   索引文件 : `src/components/{name}/index.ts`
-   测试文件 : `src/components/{name}/{name}.test.tsx`

**它更新的内容:**

-   `src/index.ts` - 添加组件导出
-   `vite.config.ts` - 添加构建条目
-   `package.json` - 添加导出配置

**示例**

```bash
? Component name: Alert Banner

✅ Component scaffolded successfully!

📁 Files created:
   - src/components/alert-banner/alert-banner.tsx
   - src/components/alert-banner/index.ts
   - src/components/alert-banner/alert-banner.test.tsx
```

脚手架工具自动处理命名 - 输入任何格式( 空间, PascalCase, kebab- case) , 它会适当转换 .

### 创建新块

Blocks是更高层次的组件,由多个基础组件组成来创建共同的页面模式. 使用块脚手架工具 :

```bash
# Create a new block
pnpm new-block
```

**它创造了什么:**

-   块文件 : `src/blocks/{name}/{name}.tsx`
-   索引文件 : `src/blocks/{name}/index.ts`
-   测试文件 : `src/blocks/{name}/{name}.test.tsx`

**它更新的内容:**

-   `src/index.ts` - 添加块导出
-   `vite.config.ts` - 添加构建条目
-   `package.json` - 添加导出配置

块是构成多块基元件的更高级组件. 见 [一般事务人员(其他职等)](https://npmcn.com/package/AGENTS.md) 关于区块的详细文件.

### 发展流动

#### 监视构建模式

测试实际文件站点或消耗性应用中的组件:

**开始监视构建 :**

```bash
pnpm dev
```

以监视模式运行 Vite, 并优化快速重建 :

-   重建时间(10x快于生产建设)
-   开发中跳过微缩
-   递增类型脚本汇编
-   选择性文件监视( ignores 测试)
-   对照生产结构产出验证组件

**使用文件网址:**

终端 1 (本目录) :

```bash
pnpm dev
```

2号航站楼(来自工作空间根或kumo-docs):

```bash
cd ../kumo-docs
pnpm dev
```

编辑组件时:

1.  Kumo 自动重建( ~ 400ms)
2.  刷新浏览器以查看 Docs 站点的变化
3.  对照实际构建产出验证更改

**构建模式 :**

-   `pnpm dev` - 开发模式(快速、优化以进行迭代)
-   `pnpm build` - 生产模式(全面优化、精密化、CSS加工)

### 测试

该包包括全面的进口验证测试,以确保所有部件都适当出口并可以消费.

**运行测试 :**

```bash
# Watch mode
pnpm test

# Single run
pnpm test:run

# With UI
pnpm test:ui

# With coverage
pnpm test:coverage
```

**测试的是什么:**

-   从主条目可导入的所有组件 : `import { Component } from "@cloudflare/kumo"`
-   所有可通过深度进口进口的部件: `import { Component } from "@cloudflare/kumo/components/component-name"`
-   从主条目导入的所有块 : `import { Block } from "@cloudflare/kumo"`
-   可通过深度进口导入的所有区块: `import { Block } from "@cloudflare/kumo/blocks/block-name"`
-   Packet.json 输出与实际组件和块同步
-   导出路径和格式正确
-   构建配置一致性

**零维护:** 测试会从文件系统自动发现组件和块并对照pack.json进行验证. 在添加新项目时,用精确的代码片段来固定配置的测试会失败.

## Beta 发布

Beta发布允许您在发布到制作前测试更改. Beta版本是自动为拉出请求而创建的并包括承诺散列以进行识别.

### 自动β释放

Beta 发布会自动被触发,以通过 GitHub 动作(`.github/workflows/package-preview-pr.yml`:

**工作流程配置 :**

-   **工作流程**数字 : `package-preview-pr.yml`
-   **触发器**: 将更改的请求拉入 `packages/kumo/**` 或者说 `.changeset/**`
-   **依赖关系**: 要求更改器存在 `@cloudflare/kumo`

**流程 :**

1.  **校验**: 确保更改程序存在 `@cloudflare/kumo`
2.  **版本**: 运行 `pnpm run version:beta`
    -   待更改的消费
    -   附录 `-beta.{commit-hash}` 改为版本编号
3.  **构建**: 运行 `pnpm --filter @cloudflare/kumo build`
4.  **发布**: 用 npm 发布 `beta` 标签
5.  **通知**: 张贴带有安装指令的PR注释

**必需的秘密 :**

-   `NPM_TOKEN`: npm 注册的认证
-   `GITHUB_TOKEN`: 用于张贴 PR 注释(内置)

### Beta 版本格式

Beta 版本遵循此模式 :

```
{base-version}-beta.{commit-hash}
```

例如: `0.1.0-beta.a1b2c3d`

### 安装 beta 版本

当一个β发布时,PR会包含一个带有安装指令的评论:

```bash
# Install the specific beta version
npm install @cloudflare/kumo@0.1.0-beta.a1b2c3d

# Or with pnpm
pnpm add @cloudflare/kumo@0.1.0-beta.a1b2c3d
```

### 测试 Beta 释放

1.  **创建 PR**: 以更改列表提交更改
2.  **等着Beta**: beta 任务在更改后自动运行
3.  **安装 beta**: 使用 PR 注释中的版本
4.  **测试更改**: 校验工程中的功能
5.  **合并**: 测试后, 将 PR 合并为生产释放

### 更改设置校验

所有有更改的拉动请求 `packages/kumo/` 必须包含更改列表 :

```bash
# Create a changeset
pnpm changeset
```

-   选择 `@cloudflare/kumo` 提示时
-   选择更改类型 : `patch`, (中文(简体) ), `minor`,或 `major`
-   写清楚的描述什么改变了

CI会在允许β发布之前自动验证一个更改et的存在.

## 生产释放量

此软件包使用 [更改](https://github.com/changesets/changesets) 用于版本管理和自动发布.

### 创建释放

1.  **检查已有的更改**数字 :
    
    ```bash
    # List any pending changesets
    ls .changeset/*.md 2>/dev/null | grep -v "README\|USAGE" || echo "No pending changesets"
    ```
    
2.  **创建更改列表** 用于修改(如有必要):
    
    ```bash
    pnpm changeset
    ```
    
    -   选择 `@cloudflare/kumo` 从列表中
    -   选择更改类型 : `patch`, (中文(简体) ), `minor`,或 `major`
    -   写清楚的描述什么改变了
    -   这创造了一个 `.changeset/*.md` 描述更改的文件

### 释放工作流程

1.  **发展**: 修改组件或块
2.  **更改集**: 创建描述这些变化的更改器
3.  **审查**: 提交带有更改和更改的 PR et
4.  **Beta 测试**: 测试向 PR 发布的β 版本
5.  **合并**: 将 PR 合并到主分支
6.  **释放**: 运行生产释放过程

### 生产释放工艺

出版发行版:

```bash
# 1. Ensure you're on main branch with latest changes
git checkout main
git pull

# 2. Version all packages (consumes changesets)
pnpm version

# 3. Build all packages
pnpm build:all

# 4. Publish to npm
pnpm release
```

这将:

-   更新 `package.json` 带有新版本
-   生成/更新 `CHANGELOG.md`
-   删除已消耗的更改et文件
-   发布到 npm 注册
-   创建 git 标签

### 释放后

出版后:

1.  **提交版本更改**数字 :
    
    ```bash
    git add .
    git commit -m "chore: release @cloudflare/kumo@{version}"
    git push
    ```
    
2.  **推动标签**数字 :
    
    ```bash
    git push --tags
    ```
    
3.  **校验出版物**数字 :
    
    ```bash
    npm view @cloudflare/kumo versions
    ```
    

### 语义版本

遵循语义版本指南 :

-   **补丁** (单位:千美元)`0.0.1`:错误修正、小组件更新、样式调整
-   **次要** (单位:千美元)`0.1.0`: 新组件,新特性,倒向相容的变化
-   **少校** (单位:千美元)`1.0.0`: 正在中断更改, 删除组件, API 更改

### 发布注释

更改器自动生成 :

-   更新 `package.json` 版本
-   `CHANGELOG.md` 带有发布注释
-   每次发行的 Git 标签

变换日志包含所有变换et描述,提供清晰的文档,说明每版中的变化.

## 解决问题

### 共同问题

**更改设置校验失败**

如果 CI 以更改et 验证错误失败 :

1.  **检查更改器是否存在**运行 `ls .changeset/*.md` 以查看待决更改
2.  **创建更改列表**运行 `pnpm changeset` 选择 `@cloudflare/kumo`
3.  **校验更改对象正确包**: 打开更改et文件并确保包括 `@cloudflare/kumo`
4.  **提交更改**: 将更改列表文件添加到您的分支

**Beta 发布失败**

如果β释放任务失败:

1.  **检查构建**: 确保 `pnpm build` 本地成功
2.  **检查 npm 令牌**: 验证 npm 认证在 CI 中配置
3.  **检查版本格式**: 确保版本遵循 semver 格式
4.  **CI 日志**: 检查 GitHub 动作日志中的特定错误消息

**发布后导入出错**

如果消费者报告进口出错:

1.  **验证出口**: 检查 `package.json` 导出符合实际文件
2.  **运行测试**: 确保 `pnpm test:run` 通过
3.  **检查构建输出**: 校验 `dist/` 包含预期文件
4.  **本地测试**: 使用 `npm link` 在发布前测试本地软件包

## 常见问题

### @cloudflare/kumo 是什么？

Kumo - Cloudflare用于构建现代网络应用程序的组件库

### 如何安装 @cloudflare/kumo？

在项目目录运行 npm install @cloudflare/kumo，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@phosphor-icons/react（^2\.1\.10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 kumo，可以用 npx kumo 直接运行。

### @cloudflare/kumo 支持 TypeScript 吗？

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

### @cloudflare/kumo 支持 ESM 还是 CommonJS？

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

### @cloudflare/kumo 可以商用吗？

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

### @cloudflare/kumo 的下载量有多少？

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

### @cloudflare/kumo 还在维护吗？

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