用法

本文由 GLM-5-turbo 驱动的 CC 根据项目源码生成

前置条件

Node.js 18+

任一包管理器：npm / pnpm / yarn / bun

Yarn Berry PnP 不支持，需切换为 node-modules linker

有效的 API Key（以 hp_ 开头）

基本用法

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

首次运行进入交互模式，hpsetup 会引导你完成所有步骤——你只需要按提示操作。

一个完整示例

假设你的项目是一个使用 pnpm 的 Next.js 项目：

# 1. 运行 hpsetup
npx -y hpsetup@latest <key>

# 2. 选择产品（多选菜单）
#    ◉ HeroUI React Pro
#    ○ HeroUI Native Pro

# 3. 检测已装包 → 查询最新版本 → 下载组件代码

# 4. 选择要安装的 peer 依赖（已全选，回车确认）
#    ◉ @heroui/react
#    ◉ @heroui/styles
#    ◉ tailwindcss
#    ...

# 5. 完成
# ✓ HeroUI React Pro v1.2.3 installed successfully.

之后每次运行，如果已是最新版本，hpsetup 会提示：

✓ HeroUI React Pro v1.2.3 — already on the latest version.
Nothing to do.

指定产品

npx -y hpsetup@latest <your_hp_key> react

pnpm dlx hpsetup@latest <your_hp_key> react

bunx hpsetup@latest <your_hp_key> react

yarn dlx hpsetup@latest <your_hp_key> react

只安装 Native Pro：

npx -y hpsetup@latest <your_hp_key> native

pnpm dlx hpsetup@latest <your_hp_key> native

bunx hpsetup@latest <your_hp_key> native

yarn dlx hpsetup@latest <your_hp_key> native

参数	产品	包名
`react`	HeroUI React Pro	`@heroui-pro/react`
`native`	HeroUI Native Pro	`heroui-native-pro`

不指定时进入交互式选择。

自动模式（CI / 脚本）

在 CI 环境或脚本中运行时，不需要任何交互：

HEROUI_KEY=<your_hp_key> npx -y hpsetup@latest

HEROUI_KEY=<your_hp_key> pnpm dlx hpsetup@latest

HEROUI_KEY=<your_hp_key> bunx hpsetup@latest

HEROUI_KEY=<your_hp_key> yarn dlx hpsetup@latest

设置 HEROUI_KEY 环境变量后，hpsetup 自动跳过所有交互提示，从 package.json 推断要安装的产品。

也可用 `--auto` 手动触发

npx -y hpsetup@latest <your_hp_key> --auto

pnpm dlx hpsetup@latest <your_hp_key> --auto

bunx hpsetup@latest <your_hp_key> --auto

yarn dlx hpsetup@latest <your_hp_key> --auto

CI 环境自带 CI=true 变量，hpsetup 会自动检测，无需额外传参。

常用选项

选项	作用
`--auto`	跳过交互提示，自动检测并安装
`--dry-run`	只显示将执行的操作，不做任何更改
`--no-cache`	绕过缓存，强制从源站拉取（每日限 1 次）
`-h, --help`	显示帮助信息

预览变更（dry-run）

不确定 hpsetup 会做什么？先 dry-run：

npx -y hpsetup@latest <your_hp_key> --dry-run

pnpm dlx hpsetup@latest <your_hp_key> --dry-run

bunx hpsetup@latest <your_hp_key> --dry-run

yarn dlx hpsetup@latest <your_hp_key> --dry-run

输出类似：

[dry-run] Would install: @heroui-pro/react
[dry-run] Would download HeroUI React Pro v1.2.3 from CDN
[dry-run] Would install peers: @heroui/react@"^2.7.0", tailwindcss@"latest"

强制刷新缓存

npx -y hpsetup@latest <your_hp_key> --no-cache

pnpm dlx hpsetup@latest <your_hp_key> --no-cache

bunx hpsetup@latest <your_hp_key> --no-cache

yarn dlx hpsetup@latest <your_hp_key> --no-cache

绕过本地缓存和 CDN 缓存，直接从源站拉取最新包。

--no-cache 每天最多使用 1 次，超出会返回 429 错误。

GitHub Actions

将 API Key 存入仓库 Secrets，在 workflow 中使用：

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx -y hpsetup@latest
        env:
          HEROUI_KEY: ${{ secrets.HEROUI_KEY }}

Vercel

首次运行时自动配置

hpsetup 检测到 Next.js 项目后，会询问是否写入 vercel.json：

Write vercel.json with installCommand for Vercel CI? [Y/n]

确认后会：

在 vercel.json 中写入 installCommand

将 vercel.json 加入 .gitignore（防止泄露 API Key）

手动配置

在 Vercel 控制台中：

Settings → Build & Development Settings → Install Command 填入：

npx -y hpsetup@latest

Environment Variables 添加：

Name: HEROUI_KEY
Value: 你的 API Key

Vercel Build 环境自带 CI=true，hpsetup 会自动进入非交互模式。

Monorepo

hpsetup 自动识别 monorepo 结构（workspaces 字段或 pnpm-workspace.yaml），无需额外配置。

自动行为

扫描所有 workspace，识别每个 workspace 的平台类型（Web / Native）

React Pro 只安装到 Web workspace，Native Pro 只安装到 Native workspace

跳过 packages/* 下的共享库

Peer 依赖按 workspace 独立扫描、独立安装

交互模式下选择 workspace

当有多个匹配的 workspace 时，会出现多选菜单让你选择安装目标。

自动模式下

所有匹配的 workspace 都会被安装，无需手动指定。

包管理器

hpsetup 自动检测当前项目使用的包管理器：

检测方式	优先级
lockfile（`pnpm-lock.yaml`、`yarn.lock` 等）	最高
`package.json` 的 `packageManager` 字段	中
`npm_config_user_agent` 环境变量	低
默认	`npm`

各包管理器的特殊处理

pnpm：

自动将 Pro 包加入 pnpm-workspace.yaml 的 allowBuilds

如果有 pending build approvals，会提示运行 pnpm approve-builds

bun：

自动将 Pro 包加入 package.json 的 trustedDependencies

npm：

安装时自动附加 --legacy-peer-deps

yarn：

仅支持 Yarn Classic，不支持 PnP

本地缓存

下载的组件代码缓存在 ~/.heroui/cache/ 目录下，按产品和版本组织：

~/.heroui/cache/
├── react/
│   ├── 1.0.0-beta.3/
│   └── 1.0.0-beta.4/
└── react-native/
    └── 1.0.0-beta.4/

相同版本不会重复下载，直接从缓存恢复。

日常使用流程

安装

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

更新

再次运行同样的命令即可。hpsetup 会自动检测新版本并更新。

CI / 构建

在 CI 配置中使用 HEROUI_KEY 环境变量，每次构建自动拉取最新版本。

排查问题

使用 --dry-run 查看将执行的操作，或 --no-cache 强制重新下载。

常见问题

pnpm + Vite 的 JSX 报错

does not provide an export named 'jsx'

这是 pnpm 严格依赖隔离的副作用。pnpm 通过符号链接组织 node_modules，Pro 组件的 JSX 转换依赖的 react/jsx-runtime 可能被解析到 Pro 包自带的副本，而非项目根目录的 React。Vite 的预构建（pre-bundling）不会自动处理这种路径差异，导致 JSX 导出找不到。

在 vite.config.ts 中手动声明依赖预构建，让 Vite 将它们打包到同一个模块中即可解决：

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react/jsx-runtime", "@heroui-pro/react"],
  },
})

用法

On this page