工作原理

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

一句话总结

hpsetup 通过 API Key 认证从 CDN 下载 HeroUI Pro 的闭源组件 tarball，解压到本地 node_modules 中已有的 stub 包内，再自动补齐 peer 依赖和包管理器信任配置。

安装全流程

npx -y hpsetup@latest hp_xxxx
         │
         ▼
   ┌─────────────┐
   │ 1. 环境检测  │  包管理器 · monorepo · 平台类型
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 2. 产品发现  │  扫描 node_modules · 识别已装版本
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 3. 版本校验  │  npm registry 查最新 · 过期则升级
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 4. 下载产物  │  CDN → 本地缓存 fallback
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 5. 信任配置  │  pnpm allowBuilds · bun trustedDeps
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 6. Peer 依赖 │  扫描缺失 · 交互确认 · 分 workspace 安装
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 7. 收尾     │  patch package.json · Vercel 配置
   └─────────────┘

模块职责

args.js — 参数解析

解析 CLI 参数和环境变量，决定交互模式还是自动模式。

install.js — 核心编排

唯一的流程控制中心，串联以下所有模块。

discover.js — 包发现

扫描 node_modules、识别 workspace 结构、检测平台类型（Web / Native）。

pm.js — 包管理器抽象

统一 npm / yarn / pnpm / bun 的 install 命令和 flag 差异。

version.js — 版本管理

查询 npm registry 最新版本，带递增超时重试（3s → 6s → 10s）。

download.js — CDN 下载

从 CDN 拉取 tarball 并解压。失败时回退到本地缓存。

cache.js — 本地缓存

缓存目录 ~/.heroui/cache/<product>/<version>/，同版本跳过下载。

peers.js — Peer 依赖

扫描缺失的 peer 依赖，处理 Expo SDK 版本兼容映射。

trust.js — 信任配置

pnpm allowBuilds / onlyBuiltDependencies，bun trustedDependencies。

patch.js — 包修补

修改 node_modules 中 Pro 包的 package.json 导出路径。

vercel.js — Vercel 适配

自动在 vercel.json 中写入 installCommand。

constants.js — 集中配置

产品定义、peer 依赖列表、Expo SDK 兼容表、CDN 地址。

关键机制详解

Stub 包与真实产物

npm 上的 HeroUI Pro 包是 stub 包——只包含一个 postinstall 脚本，不含真实组件代码。hpsetup 的工作就是：

用 --ignore-scripts 安装 stub 包（使 node_modules/@heroui-pro/react 目录存在）

从 CDN 下载包含真实组件代码的 tarball

解压到 stub 包目录中，覆盖空壳内容

hpsetup 通过检查产物目录中是否存在 index.js 或 index.mjs 来判断"是否已安装真实代码"，而非仅看包是否存在。

Monorepo 支持

hpsetup 自动检测 workspace 结构（package.json 的 workspaces 字段、pnpm-workspace.yaml），并智能定位安装目标：

自动识别平台：通过依赖和配置文件判断每个 workspace 是 Web 还是 Native 项目

精确安装：React Pro 只装到 Web workspace，Native Pro 只装到 Native workspace

跳过共享库：packages/* 路径下的纯库包不会被作为安装目标

分 workspace 安装 peer 依赖：每个 workspace 独立扫描、独立安装

下载容错

CDN 下载 → 当前版本缓存 → 上一版本缓存 → 退出报错

三层 fallback 确保在网络波动或 CDN 不可用时仍能完成安装。

包管理器信任

HeroUI Pro 包含 postinstall 脚本，需要包管理器信任才能执行。hpsetup 自动处理：

包管理器	信任方式
pnpm（有 workspace）	`pnpm-workspace.yaml` 的 `allowBuilds` 字段
pnpm（无 workspace）	`package.json` 的 `pnpm.onlyBuiltDependencies` 字段
bun	`package.json` 的 `trustedDependencies` 字段
npm / yarn	无需额外配置

Vercel 集成

当检测到 Next.js 项目时（存在 next.config.* 或 vercel.json），hpsetup 会提示在 vercel.json 中写入 installCommand，使 Vercel 构建时自动运行 hpsetup。同时将 vercel.json 加入 .gitignore，避免泄露 API Key。

Expo SDK 兼容

安装 Native Pro 时，hpsetup 读取项目中的 Expo SDK 主版本号，自动将 peer 依赖版本映射到 Expo 兼容的固定版本：

Expo SDK	`@shopify/react-native-skia`
52	1.5.0
53	2.0.0-next.4
54	2.2.12
55	2.4.18

这些版本通过 npx expo install 逐个 SDK 测试确认兼容。

交互模式 vs 自动模式

	交互模式	自动模式（`--auto` 或 CI）
触发条件	TTY 终端	`CI=true` 或 `--auto`
产品选择	多选菜单	从 package.json 自动推断
Workspace 选择	多选菜单	全部匹配的 workspace
Peer 依赖确认	多选菜单（可取消勾选）	全部安装，无确认
Vercel 配置	询问确认	直接写入

已知限制

不支持 Yarn Berry PnP：需在 .yarnrc.yml 中添加 nodeLinker: node-modules，或使用其他包管理器

pnpm + Vite：可能出现 does not provide an export named 'jsx' 错误，需在 vite.config 中添加 optimizeDeps.include

--no-cache 频率限制：每日最多 1 次，超限返回 429