hpsetup - HeroUI Pro 安装指南

一条命令安装 HeroUI Pro 组件，无需 GitHub 登录，支持所有包管理器。

当前状态

● @heroui-pro/react v1.0.0-beta.2 — 可用（CDN 缓存固化）
● heroui-native-pro — 暂不可用
● 上游 CDN 不可用 — 仅支持已缓存的版本，新版本暂无法获取

这是什么？

hpsetup 是一个 npm 包，用于替代官方的 npx heroui-pro install 安装流程。

官方安装需要 GitHub OAuth 登录 + 交互式 CLI。hpsetup 只需要一个 Key，即可在任何环境（本地开发、CI/CD、团队协作）中一键完成安装。

hpsetup 会自动检测项目中的 Pro 包，从 CDN 缓存下载组件。安装结果与官方完全一致。

快速开始

创建项目

如果你还没有 HeroUI 项目，先创建一个：

npx heroui-cli@latest init my-heroui-app
cd my-heroui-app

用你喜欢的包管理器安装依赖：

pnpm install

npm / yarn / bun 均可，hpsetup 会自动检测。

安装 HeroUI Pro

运行 hpsetup，将 <YOUR_HP_KEY> 替换为你收到的 Key：

npx -y hpsetup@latest <YOUR_HP_KEY>

你会看到类似输出：

Detected: @heroui-pro/react
Adding @heroui-pro/react v1.0.0-beta.2 via pnpm...
Downloading @heroui-pro/react v1.0.0-beta.2...
  CDN: https://cdn.932324.xyz
  Cache: HIT (cached) | 380 KB
Installing 18 dependencies...
Resolving transitive dependencies...
Writing files for @heroui-pro/react...
Removed install scripts for @heroui-pro/react ✓

Done ✓

Inject HEROUI_KEY into .env.local and configure Vercel? [y/N]

原理：hpsetup 会自动检测项目中的 HeroUI Pro 包（@heroui-pro/react 和/或 heroui-native-pro），先安装空壳包，然后从 CDN 缓存下载真正的组件代码覆盖到 node_modules 中，最后补装所有依赖。最终结果与官方安装完全一致。

引入样式

在你的全局 CSS 文件末尾新增一行：

使用组件

创建组件文件 components/area-chart-demo.tsx：

在页面中引入组件：

启动开发服务器：

pnpm dev

打开浏览器访问 http://localhost:5173 即可看到效果。

React Native

暂不可用 — heroui-native-pro 的组件包尚未缓存，当前无法安装。后续恢复后会在此处更新。

hpsetup 支持 HeroUI Native Pro（heroui-native-pro），适用于 Expo 和 React Native 项目。缓存恢复后即可按以下步骤使用：

前置条件

已安装 HeroUI Native OSS（heroui-native）
Tailwind CSS v4 via Uniwind

安装 HeroUI Native Pro

添加依赖：

npx expo install heroui-native-pro

运行 hpsetup：

npx -y hpsetup@latest <YOUR_HP_KEY>

你会看到类似输出：

Detected: heroui-native-pro
Adding heroui-native-pro v1.0.0-beta.2 via npm...
Downloading heroui-native-pro v1.0.0-beta.2...
  CDN: https://cdn.932324.xyz
  Cache: MISS (fetching from upstream) | 856 KB
Installing 2 dependencies...
Resolving transitive dependencies...
Writing files for heroui-native-pro...
Removed install scripts for heroui-native-pro ✓

Done ✓

配置样式

在 global.css 中添加 Pro 包的样式和 source 路径：

使用组件

示例——使用 Stepper 组件：

import { Stepper } from 'heroui-native-pro';
import { View } from 'react-native';

export default function MyScreen() {
  return (
    <View className="flex-1 justify-center bg-background p-4">
      <Stepper>
        <Stepper.Step>
          <Stepper.Rail />
          <Stepper.Content>
            <Stepper.Title>Account</Stepper.Title>
            <Stepper.Description>Create your account</Stepper.Description>
          </Stepper.Content>
        </Stepper.Step>
        <Stepper.Step>
          <Stepper.Rail />
          <Stepper.Content>
            <Stepper.Title>Profile</Stepper.Title>
            <Stepper.Description>Set up your profile</Stepper.Description>
          </Stepper.Content>
        </Stepper.Step>
      </Stepper>
    </View>
  );
}

常见问题

pnpm + Vite 报错 "does not provide an export named 'jsx'"

这是 pnpm 严格模块解析与 Vite 预构建机制的兼容性问题，与安装方式无关。在 vite.config.ts 中添加：

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

支持 React Native / Expo 吗？

hpsetup 代码层面已支持 heroui-native-pro，但由于上游 CDN 不可用，该包的组件暂未缓存，当前无法安装。缓存恢复后即可使用。

目前可用的只有 @heroui-pro/react（Web）v1.0.0-beta.2。

支持哪些包管理器？

npm、pnpm、yarn、bun 均支持。hpsetup 会自动检测你项目使用的包管理器。

支持哪些操作系统？

macOS、Linux、Windows（PowerShell / cmd / Git Bash）。

如何指定安装版本？

npx -y hpsetup@latest <YOUR_HP_KEY> 1.0.0-beta.2

Key 可以用在 CI/CD 中吗？

可以。设置环境变量即可：

HEROUI_KEY=hp_xxx npx -y hpsetup@latest

CI 环境下 hpsetup 会自动跳过交互式确认，直接完成安装。

Vercel / Netlify 部署怎么配置？

首次本地运行 hpsetup 时，会提示你是否注入环境变量文件和配置 Vercel。确认后 hpsetup 会自动：

将 HEROUI_KEY 写入 .env / .env.local / .env.production 等文件
创建 .env.example（占位符，可提交到 Git）
生成或更新 vercel.json 的 installCommand

然后在 Vercel Dashboard 中添加环境变量 HEROUI_KEY 即可。之后每次部署会自动运行 hpsetup。

{
  "installCommand": "pnpm install --ignore-scripts && pnpm dlx hpsetup"
}

VPS / Docker / GitHub Actions 怎么部署？

任何 CI 环境都支持。设置 HEROUI_KEY 环境变量后，在 install 阶段运行 hpsetup 即可：

通用：install 后手动跑 hpsetup

npm install --ignore-scripts
HEROUI_KEY=hp_xxx npx -y hpsetup@latest

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
ENV HEROUI_KEY=hp_xxx
RUN npm install --ignore-scripts && npx -y hpsetup@latest
COPY . .
RUN npm run build
CMD ["node", "server.js"]

GitHub Actions

- name: Install dependencies
  env:
    HEROUI_KEY: ${{ secrets.HEROUI_KEY }}
  run: |
    npm install --ignore-scripts
    npx -y hpsetup@latest
- name: Build
  run: npm run build

关键点：--ignore-scripts 跳过官方包的 postinstall，然后 hpsetup 替换为真实组件。CI 环境下 hpsetup 自动跳过交互式确认。

hpsetup 和官方安装有什么区别？

安装结果完全一致。 官方 CLI 通过 GitHub OAuth 登录后从 CDN 下载组件，hpsetup 通过代理完成同样的下载过程。最终写入 node_modules/@heroui-pro/react/ 或 node_modules/heroui-native-pro/ 的文件完全相同——组件代码、样式、类型定义没有任何区别。

下载速度慢怎么办？缓存是怎么工作的？

hpsetup 的 CDN 代理内置了版本级缓存：每个版本只回源一次，之后所有用户安装同一版本时直接从缓存读取，速度极快。安装时会显示缓存状态：

Cache: HIT (cached) — 从缓存读取，秒级完成
Cache: MISS (fetching from upstream) — 首次安装该版本，从上游拉取

缓存 TTL 为 30 天。由于版本号固定在缓存 key 中，同一版本号对应的 tarball 永远不会变化，因此缓存命中后几乎不会过期。新版本发布时自动触发新的缓存条目。