# @cloudwick/astral-ui-cli 中文文档

规范地址：https://npmcn.com/package/%40cloudwick/astral-ui-cli/

版本：2\.5\.0
npm 元数据更新时间：2026-10-26T06:52:45.128Z
中文译文更新时间：2026-11-10T03:53:28.840Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudwick/astral-ui-cli
原文对照：https://npmcn.com/package/%40cloudwick/astral-ui-cli/?lang=original

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

- 包体积（解压后）：4.8 MB，50 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：11 个
- 首次发布：2025-05-14T15:11:03.077Z
- 最新版本发布：2026-10-26T06:52:44.879Z
- 近 30 天下载量：3421（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 8 个）

## 中文简介

用于在任意编码库中安装 Astral UI 组件的 CLI

## 安装

```sh
npm install @cloudwick/astral-ui-cli
```

也可以使用：`pnpm add @cloudwick/astral-ui-cli`、`yarn add @cloudwick/astral-ui-cli`、`bun add @cloudwick/astral-ui-cli`

## README

# Astral UI 类CLI

一个用于安装和管理 Astral UI 组件在任意代码库中的命令行工具.

## 使用量

对于大多数项目,我们建议使用CLI与 `npx` 或者说 `yarn dlx` 而不是在全球安装:

```bash
# Using npx
npx @cloudwick/astral-ui-cli init

# Using yarn
yarn dlx @cloudwick/astral-ui-cli init
```

如果您在工作流程中频繁使用 CLI, 您可以在全球安装 :

```bash
# Install globally with npm (only if needed)
npm install -g @cloudwick/astral-ui-cli

# Install globally with yarn (only if needed)
yarn global add @cloudwick/astral-ui-cli
```

## 快速启动

```bash
# Initialize your project
npx @cloudwick/astral-ui-cli init

# Add components
npx @cloudwick/astral-ui-cli add button card

# Start using in your code
import { Button } from '@components/button';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';
import { useWindowSize } from '@hooks';
```

## 工作流程

最好的经验是,遵循这些步骤,以便:

1.  **初始化** 您的项目与 `npx @cloudwick/astral-ui-cli init` - 这将显示您工程类型的路径化名设置指令
2.  **配置路径别名** 在工程中遵循初始化时显示的指令
3.  **添加组件** 与 `npx @cloudwick/astral-ui-cli add [component...]`
4.  **修复尾风** 如果需要的话 `npx @cloudwick/astral-ui-cli repair-tailwind`
5.  **进口和使用** 应用程序中的组件

## 图标

### `init`

以 Astral Core 配置初始化项目 .

```bash
npx @cloudwick/astral-ui-cli init
```

此命令将 :

-   创建一个 `components.json` 配置文件
-   建立必要的依赖关系
-   如果还没有安装尾风 CSS
-   在现有 Tailwind 配置中添加所需的配置或创建新配置
-   添加工具函数
-   为一致的打字法添加Noto Sans字体文件
-   为适当的字体渲染设置字体 CSS
-   根据您的工程类型( Next.js, Vite, Webpack, CRA等) 显示详细的路径别名设置指令

#### 选项

| 选项 | 别名 | 说明 |
| --- | --- | --- |
| `--yes` | `-y` | 跳过确认提示 |
| `--defaults` | `-d` | 使用默认配置 |
| `--cwd <dir>` | `-c` | 指定工作目录 |
| `--silent` | `-s` | 静音输出 |

**说明:** 当文件已经存在时,在替换之前会自动创建备份.

Init 命令自动检测您的工程类型,并提供特定路径别名配置指令,用于:

-   **下一个.js**:别名使用tsconfig.json/jsconfig.json
-   **维特**: 提供 vite.config.js/ts 配置
-   **网络软件包**: 提供webpack.config.js配置
-   **创建反应应用**提供 CRACO 设置指令
-   **常规**: 为其他项目类型提供基础配置

此外,CLI还检测了tsconfig.app.json(被一些框架用于特定应用程序的TypeScript设置)并提供了配置指南.

### `add`

在您的工程中添加组件 .

```bash
npx @cloudwick/astral-ui-cli add [component...]
```

#### 选项

| 选项 | 别名 | 说明 |
| --- | --- | --- |
| `--cwd <dir>` | `-c` | 指定工作目录 |
| `--all` | `-a` | 添加所有可用的组件 |
| `--path <path>` | `-p` | 指定将组件添加到的路径 |
| `--silent` | `-s` | 静音输出 |
| `--skip-dependencies` |  | 跳过安装内部组件依赖性 |
| `--list` | `-l` | 列出所有可用的组件 |

**说明:** 当一个组件已经存在时, 在替换之前会提示您 。 替换时自动创建备份 .

#### 实例

```bash
# List all available components
npx @cloudwick/astral-ui-cli add --list

# List components in silent mode (component names only)
npx @cloudwick/astral-ui-cli add --list --silent

# Add specific components
npx @cloudwick/astral-ui-cli add button card select

# Add all components
npx @cloudwick/astral-ui-cli add --all

# Add a component to a specific directory
npx @cloudwick/astral-ui-cli add button --path ./components/custom

# Skip installing internal component dependencies
npx @cloudwick/astral-ui-cli add button --skip-dependencies
```

### `repair-tailwind`

设置失败时修复 Tailwind 配置 - 仅在遇到 Tailwind 问题时使用 .

```bash
npx @cloudwick/astral-ui-cli repair-tailwind
```

此命令将 :

-   检查已有的 Tailwind 配置并创建时间标记的备份
-   为您的工程创建新的带有相应文件扩展名的 Tailwind 配置
-   建立完整的CSS结构,包括:
    -   主要 CSS 文件, 包含适当的导入
    -   字体样式表( fonts.min.css)
-   确保安装适当的依赖性
-   在修改前创建已存在的 Tailwind 配置的备份

创建的 CSS 结构将完全符合 `init` 命令创建,包括:

-   颜色和主题的 CSS 变量
-   字体导入和配置
-   适当的文件组织

#### 选项

| 选项 | 别名 | 说明 |
| --- | --- | --- |
| `--cwd <dir>` | `-c` | 指定工作目录 |
| `--silent` | `-s` | 静音输出 |

**说明:** 该命令在替换已存在的文件并自动创建备份前会提示.

#### 示例使用

```bash
# Basic repair
npx @cloudwick/astral-ui-cli repair-tailwind

# Repair in a specific directory
npx @cloudwick/astral-ui-cli repair-tailwind --cwd ./my-project
```

## 配置

### 组件.json

这个 `components.json` 文件在初始化时创建, 并包含您的项目的配置 :

```json
{
  "$schema": "./schema/components-config.schema.json",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/globals.css",
  },
  "aliases": {
    "components": "src/components",
    "utils": "src/utils",
    "constants": "src/constants",
    "hooks": "src/hooks"
  }
}
```

您可以编辑此文件以自定义 :

-   **尾风. 配置**: 您的 Tailwind 配置文件路径
-   **密码**: 您全局 CSS 文件的路径
-   **别名**: 安装组件、公用设施、常数和钩子的路径

> **说明**编号: `utils` 路径在 `components.json` 在没有文件扩展名的情况下存储。 CLI 自动添加 `.ts` 或者说 `.js` 基于您项目是否使用 TypeScript 或 JavaScript 的扩展。 在配置路径别名时,您应当使用路径,而无需显示扩展名 `components.json` 文档.

### JSON Schema 组件

和你的一样 `components.json`, CLI 生成一个 JSON Schema 文件 `schema/components-config.schema.json`。 。 。 . 您可以在编辑器或 CI 中使用这个方案来验证您的配置 。 它定义:

-   `$schema` (字符串):这个计划文件的URI.
-   `tailwind` (对象):您 Tailwind 配置的路径( )`config`)和 CSS 文件 (`css`) (中文(简体) ).
-   `aliases` (对象):用于 `components`, (中文(简体) ), `utils`, (中文(简体) ), `constants`,以及 `hooks`编辑 `hooks` 条目是可选的 —— 由更古老的 CLI 版本所创建的配置省略并返回到 `src/hooks` (单位:千美元)`lib/hooks` 下册.

详情见 `schema/components-config.schema.json` 在你的项目.

## 可用组件

要看到所有可用组件的完整列表, 请运行 :

```bash
npx @cloudwick/astral-ui-cli add --list
```

这将显示所有组件及其描述 。 您也可以使用无声模式获取组件名称 :

```bash
npx @cloudwick/astral-ui-cli add --list --silent
```

### 大众成分

| 构成部分 | 说明 |
| --- | --- |
| `button` | 具有不同样式、大小和状态的按钮组件 |
| `card` | 用于以包含的方式显示内容的卡片组件 |
| `select` | 从列表中选择选项的选定组件 |

## 使用组件

添加组件后,您可以在应用程序中导入和使用:

### 反应/下一步js 示例

```tsx
import { Button } from '@components/button';
import { Card, CardHeader, CardContent } from '@components/card';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';

export function MyComponent() {
  return (
    <Card>
      <CardHeader>My Card</CardHeader>
      <CardContent>
        <p>Card content goes here</p>
        <Button 
          className={cn("mt-4", "custom-class")}
          variant="outline"
        >
          Click Me
        </Button>
      </CardContent>
    </Card>
  );
}
```

### 关于 Utils 文件

CLI 创建工具文件 `cn` 帮助结合 Tailwind 类的函数。 此文件 :

-   是在路径中指定的初始化过程中自动创建的 `components.json` (单位:千美元)`utils` 字段)
-   拥有相应的文件扩展名( N)`.ts` 用于类型脚本项目, `.js` 为 JavaScript 项目自动添加)
-   应在组件中导入为 `import { cn } from '@utils'` 设置路径别名后

这个 `cn` 函数允许您有条件地合并类名并自动处理 Tailwind 类冲突.

### 关于虎克目录

CLI还安装了共享反应钩的目录(`useAsyncOptions`, (中文(简体) ), `useFilterQuery`, (中文(简体) ), `useInfiniteScroll`, (中文(简体) ), `useListboxKeyboardNav`, (中文(简体) ), `useIsTruncated`, (中文(简体) ), `useWindowSize`页:1 此目录 :

-   是在路径中指定的初始化过程中自动创建的 `components.json` (单位:千美元)`hooks` 字段)
-   暴露通过 `@hooks` 化名,必须同时配置 `@components`, (中文(简体) ), `@utils`,以及 `@constants`
-   是由几个组成部分要求的—— `Select`, (中文(简体) ), `TransferList`, (中文(简体) ), `MultiSelectTransfer`, (中文(简体) ), `Scrollbar`,以及 `CtaGroup` 全部导入自 `@hooks`,所以这些组件如果没有这个化名将无法解决

导入钩子为 `import { useWindowSize } from '@hooks'` 总是从枪管,而不是从个人文件.

## 样式组件

登记册中的组件需要 Tailwind CSS 在您的应用程序中进行适当的配置 。 当你跑的时候 `npx @cloudwick/astral-ui-cli init`国家行动倡议将:

1.  检查已有的 Tailwind 配置并升级到必要的设置
2.  创建一个 CSS 文件, 包含组件样式所需的 CSS 变量
3.  生成一个 STYLING. md 文件, 包含关于样式系统的文档

### 尾风集成

CLI 智能地处理现有的 Tailwind 配置 :

-   自动检测带有任何扩展名的现有配置文件(.js,.ts,.mjs,.cjs)
-   创建任何已存在的 Tailwind 配置文件的时间戳备份
-   根据您的工程类型创建新的尾风. config 文件并附带适当的扩展名 :
    -   类型脚本项目 : `.ts` 扩展
    -   无害环境管理项目: `.mjs` 扩展
    -   普通JS项目: `.js` 扩展
    -   无害环境管理包中常见的JS(有"类型":"模块"): `.cjs` 扩展
-   保存您的工程语言( TypeScript 或 JavaScript) 和模块系统( ESM 或 CommunityJS)

配置中包含必要的尾风特性 :

-   有 RGB 变量的颜色系统,用于初级、二级、成功、警告、出错和灰色平面
-   自定义卡片组件的框阴影
-   暗模式支持( 主题拖动的“ 类” 模式)

### CSS 变量

CSS文件包括所有必要的CSS变量,这些变量构成参考内容,包括:

-   基本颜色(初级、二级等)
-   状态颜色( 成功、 错误、 警告)
-   光/暗模式的主题变量

## 解决问题

### 别名问题

如果你对进口有问题:

1.  **检查您的配置**: 确保 tsconfig.json/jsconfig.json中的路径与您的工程结构相匹配. 所有四个别名都需要: `@components/*`, (中文(简体) ), `@utils`, (中文(简体) ), `@constants`,以及 `@hooks`A级 `Cannot find module '@hooks'` 错误表示缺少别名 .
2.  **二. 具体框架问题**数字 :
    -   **下一个.js**: 确保您正在使用正确的导入格式用于您的 Next.js 版本
    -   **tsconfig.app.json (英语)**: 如果您的工程使用 tsconfig.app.json , 请配置此路径
    -   **创建反应应用**: 您需要 CRACO 或类似的路径名才能启用
3.  **校验设置**: 路径别名设置指令显示在 `init` - 你可以跑开 `npx @cloudwick/astral-ui-cli init` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}再次见到他们
4.  **检查组件. json**: 确保“别名”部分中的路径与您的工程结构相匹配

### 造型问题

如果组件的样式不正确:

1.  确保 Tailwind CSS 配置在您的应用程序中正确加载
2.  校验 CSS 变量包含在您的 CSS 主文件中
3.  检查您的组件是否正在正确导入所需的公用事业
4.  运行 `npx @cloudwick/astral-ui-cli repair-tailwind` 创建新的尾风配置
5.  如果您需要将新配置与您现有的定制合并, 请使用您的备份文件作为参考

## 捐款

关于发展和促进国家行动倡议的资料,请参见: [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 在寄存器根中的文件.

## 许可证

麻省理工学院

## 常见问题

### @cloudwick/astral-ui-cli 是什么？

用于在任意编码库中安装 Astral UI 组件的 CLI

### 如何安装 @cloudwick/astral-ui-cli？

在项目目录运行 npm install @cloudwick/astral-ui-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 astral-ui，可以用 npx astral-ui 直接运行。

### @cloudwick/astral-ui-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cloudwick\_\_astral-ui-cli 是否存在。

### @cloudwick/astral-ui-cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cloudwick/astral-ui-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudwick/astral-ui-cli 可以商用吗？

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

### @cloudwick/astral-ui-cli 的下载量有多少？

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

### @cloudwick/astral-ui-cli 还在维护吗？

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