@heybox/hb-sdk

Appearance

安装 ​

@heybox/hb-sdk 同时提供小程序页面使用的 SDK、hb-sdk CLI 和 Vite 构建插件。第一次接入时，推荐直接创建官方模板；已有 Vite 项目则按本页手动安装。

准备环境 ​

  • 使用官方模板和 CLI 时，需要 Node.js >=22.20.0。
  • SDK 必须安装在小程序页面项目中，并从公开入口 @heybox/hb-sdk 导入。
  • @heybox/hb-sdk 应放在 dependencies，因为页面运行时会加载它；不要只放在 devDependencies。

如果页面完全不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装 SDK。

方式一：创建新项目 ​

在准备放置项目的目录中运行：

bash
npx @heybox/hb-sdk@latest create my-miniapp
cd my-miniapp
npm install
npm run hb-sdk -- login
npm run hb-sdk -- remote create
# 已有远端小程序时改用：npm run hb-sdk -- remote bind <mini-program-id>
npm run dev

create 会生成 Vanilla JavaScript、Vite 和 npm 项目，但不会自动安装依赖、初始化 Git 或打开编辑器。目标目录必须为空，项目名使用 my-miniapp 这类合法的非 scoped npm 包名。模板页面是可直接删除的 HelloWorld，不绑定 Vue、TypeScript 或测试框架。

本页使用 @latest 创建项目，实际安装版本以 npm 的 latest 为准。

模板已经配置好以下内容，无需重复添加：

  • @heybox/hb-sdk 运行时依赖。
  • hb-sdk dev 本地开发命令。
  • miniappManifest() Vite 插件和相对资源路径。
  • package.json#heybox 版本名称与占位图片；提交审核前必须替换占位图。
  • package.json#heybox.platforms 目标平台声明。
  • hb-sdk build 生产构建和 hb-sdk remote deploy 提交审核脚本。

npm run dev 在校验 CLI 登录态、项目绑定与远端配置后启动页面服务和内置本地调试页；未满足前置条件时会退出并给出修复指引。请先完成 CLI 登录并创建或绑定远端小程序；真机调试还需有效启动票。如果浏览器没有自动打开，请访问终端输出的调试地址。

方式二：接入已有 Vite 项目 ​

已有项目需要 Vite 5 或更高版本。先把 SDK 安装为运行时依赖：

bash
npm install @heybox/hb-sdk

也可以使用项目已有的包管理器：

bash
pnpm add @heybox/hb-sdk
yarn add @heybox/hb-sdk
bun add @heybox/hb-sdk

先在 package.json#heybox 中声明版本名称、项目内图片和实际承诺适配的平台。以下五个平台是官方模板的起始默认，发布前应替换示例图片，并按实际适配和真机验收结果调整平台：

json
{
  "heybox": {
    "name": "我的小程序",
    "icon": "assets/icon.png",
    "coverImages": ["assets/cover.png"],
    "platforms": ["android", "ios", "ohos", "windows", "macos"]
  }
}

图片必须真实存在并符合格式、尺寸和大小要求，完整规则见版本名称与图片。heybox 中还可以声明权限、窗口尺寸、关联游戏和桌面辅助应用，并记录当前项目绑定的远端小程序。字段总览、完整示例与校验规则见 package.json 项目配置。

再在 vite.config.ts 中注册构建插件。保留项目已有的框架插件，例如下面的 vue()：

ts
import vue from '@vitejs/plugin-vue'
import { miniappManifest } from '@heybox/hb-sdk/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  base: './',
  plugins: [vue(), miniappManifest()],
})

miniappManifest() 会准备工坊小程序的开发环境，校验版本资料与 package.json#heybox.platforms，复制图片产物，并在生产构建时把名称、图片路径和规范化平台声明写入 dist/manifest.json。插件只允许 base 使用空字符串或 './'；未配置时会自动使用 './'。

生产构建对 Vite 编译打包的脚本统一使用 Chrome 64 / Safari 12 的 JavaScript 语法兼容下限。项目设置更旧的 build.target 时继续按更保守的目标转换；esnext、更高版本目标和 Vite 环境级目标不能覆盖该下限。不要在生产配置中设置 esbuild: false，否则会明确报错。开发服务不受该约束。原样复制的 public/ 脚本和远端脚本不会经过这项转换；这里也不自动补齐 Object.fromEntries 等运行时 API，不能替代真机验收。已有小程序需要升级到包含此修复的 SDK 并重新构建、提交和发布，已上线的旧包不会自动变化。

若当前版本需要关联 PC 游戏，可在 heybox 中增加 "bindAppIds": ["730", "3513350"]。该字段是版本发布元数据而非 Runtime 权限：本地构建只做离线格式校验，远端 deploy 会在上传前校验游戏，提审时再次校验。缺失或空数组表示清空绑定；复用历史产物时继承源版本绑定。工作区发现还会按 platforms 过滤。

再把项目的开发命令指向 CLI：

json
{
  "scripts": {
    "hb-sdk": "hb-sdk",
    "dev": "hb-sdk dev",
    "build": "vue-tsc --noEmit && hb-sdk build"
  }
}

hb-sdk build 直接使用项目安装的 Vite 构建固定的 dist/，自身不执行类型检查；示例把项目已有的 vue-tsc 检查保留在 scripts.build 中。现有 vite build 脚本仍然兼容，不会自动迁移。若默认端口被占用，可以通过 hb-sdk dev --port <port> --browser-dev-host-port <port> 指定页面和 Browser Dev Host 端口。CLI 会从当前项目解析已安装的 Vite，不需要全局安装 hb-sdk。

导入 SDK ​

在页面启动逻辑中导入默认实例。SDK 会自动启动握手，所有能力调用会自动等待 SDK 就绪：

ts
import hbSDK from '@heybox/hb-sdk'

async function getCurrentUser() {
  const result = await hbSDK.user.getInfo()
  return result.userInfo
}

业务代码只从包的公开入口导入 SDK，不要使用内部文件路径。user.getInfo() 与 auth.login() 都要求在 package.json#heybox.permissions 声明 userInfo，但不依赖公开 network 权限；前者读取当前用户的隔离身份和已授权资料，后者应在用户操作中调用并把短期 code 交给开发者服务端。安装验证只需确认调用成功，不必展示返回资料。

确认安装成功 ​

运行：

bash
npm run hb-sdk -- login
npm run hb-sdk -- remote create
# 已有远端小程序时改用：npm run hb-sdk -- remote bind <mini-program-id>
npm run dev

安装正确时，浏览器会打开本地调试页并正常加载小程序。常见问题按下面顺序检查：

  1. 真机入口提示缺少 CLI 登录态或项目绑定：先执行上面的 login 和 remote create / remote bind；Browser Mock 不要求登录或绑定。
  2. 提示找不到 Vite：先安装项目依赖，并确认 vite 在项目依赖或开发依赖中。
  3. SDK 握手超时：确认是从 npm run dev 打开的本地调试页进入，而不是直接打开页面服务地址。
  4. 真机无法访问：确认手机和电脑在同一局域网，并在调试页重新选择正确网卡。
  5. 生产构建提示版本无效：确认项目 package.json.version 是合法 SemVer；官方模板初始值为 0.1.0。

更完整的端口、CLI 登录、绑定和真机调试说明见 CLI 与本地 mock 调试，SDK 初始化与身份接入见 快速开始。

可选：安装 Agent Skill ​

Agent Skill 用于让 Codex 等 AI Agent 获得 hb-sdk 的开发约束，不是 SDK 的运行依赖。需要时单独安装：

bash
hb-sdk skill install

版本校验和刷新方式见 Agent Skill 安装。

TypeScript 类型 ​

业务侧类型也从根入口导入：

ts
import type {
  MiniProgramEventHandler,
  MiniProgramEventName,
  LoginResult,
  GetUserInfoResult,
} from '@heybox/hb-sdk'