@heybox/hb-sdk

Appearance

常见问题 ​

适用于小程序工坊开发者，整理接入、调试、能力调用、审核发布和反馈过程中常见的问题。各回答提供排查方向，完整操作以链接的专题文档为准。

开始开发 ​

创建小程序前需要申请开发者资格吗？ ​

小程序工坊已进入公测，可以直接登录小黑盒开放平台创建和管理小程序。背景与运行边界见什么是小程序工坊。

必须使用 Vue 或 TypeScript 吗？ ​

不需要。官方模板使用 JavaScript 和 Vite，可以按项目需要选择框架或 TypeScript。已有 Vite 项目也可以接入 SDK，见安装。

安装或创建项目失败，先检查什么？ ​

先确认 Node.js 满足安装指南要求，再检查项目依赖是否安装完整、创建目录是否为空。使用已有项目时，确认项目已安装兼容的 Vite 和 @heybox/hb-sdk，并配置构建插件。环境要求与接入示例见安装。

终端提示找不到 hb-sdk 或 Vite 怎么办？ ​

在项目目录安装依赖，优先通过项目已有的 npm 脚本运行命令。CLI 使用项目安装的 Vite；不需要依赖全局安装的 CLI。具体配置见安装。

CLI 登录与小程序里的用户登录是同一回事吗？ ​

不是。hb-sdk login 用于本地开发和远端管理；小程序页面中的登录与用户授权由 SDK 的用户能力处理。CLI 已登录不代表页面用户已经授权，见用户身份与登录。

已有远端小程序，怎样让本地项目关联它？ ​

登录 CLI 后，在项目目录执行 hb-sdk remote bind <mini-program-id>。新建远端小程序则使用 hb-sdk remote create。绑定与远端管理方式见CLI 与本地 mock 调试。

本地调试 ​

没有登录或绑定项目，可以先调试页面吗？ ​

需要先完成 CLI 登录和项目绑定，hb-sdk dev 校验远端配置后才会启动 Browser Mock。未登录或未绑定时会直接退出并提示修复命令；启动后的签票失败或临时断网仍保留浏览器调试，见CLI 与本地 mock 调试。

SDK 握手超时、页面无法连接宿主怎么办？ ​

确认从 hb-sdk dev 打开的调试台进入小程序，而不是直接打开页面服务地址。生产构建应在小黑盒客户端的受控沙箱中运行，不能当作普通网页直接运行。接入检查见安装。

调试端口被占用怎么办？ ​

通过 hb-sdk dev --port <port> --browser-dev-host-port <port> 调整页面和调试台端口，再使用本次启动输出的新地址。参数说明见CLI 与本地 mock 调试。

手机无法扫码进入小程序怎么办？ ​

确认 CLI 已登录、项目已绑定，并查看调试台是否提示真实设备入口不可用。局域网调试地址需要手机能够访问电脑：先连接同一局域网，再选择手机可达的 Network 地址，并扫描当前二维码。仍失败时保留 hb-sdk dev --verbose 的诊断信息。

调试页面没有自动打开怎么办？ ​

复制终端输出的调试地址到浏览器，并检查启动参数中是否使用了 --no-open。

需要进一步排查时，运行 hb-sdk dev --verbose。完整流程见CLI 与本地 mock 调试。

浏览器调试正常，为什么客户端仍然报错？ ​

浏览器 Mock 用于本地开发，不能代替真实客户端验收。请在目标客户端检查能力支持、权限声明和实际授权情况，并保留错误信息用于排查。

相关说明见权限声明、错误处理和API 兼容性。

权限、用户与开放能力 ​

已在项目中声明权限，为什么调用仍然失败？ ​

权限声明、平台批准、用户授权和客户端能力支持需要分别满足。请根据错误码确认缺少哪一项，再调整配置或交互；只添加声明不能替代其他条件。完整检查见权限声明。

权限未声明与权限被拒绝有什么区别？ ​

PERMISSION_NOT_IN_SNAPSHOT 表示当前运行快照缺少所需权限：正式入口需发布包含声明的新版本，开发入口更新声明后重新打开调试会话。旧 Runtime 仍可能返回 PERMISSION_NOT_DECLARED；PERMISSION_DENIED 表示所需的平台批准缺失或不足。完整处理与申请入口见权限声明。

提示需要用户操作，或用户取消了授权，怎么办？ ​

需要授权的操作应放在用户明确点击之后。提示 USER_GESTURE_REQUIRED 时检查触发方式；用户取消授权或文件选择时，正常结束本次操作，允许用户之后再次发起。见错误处理。

获取用户信息时没有昵称、头像或 Steam 信息，是出错了吗？ ​

这些资料取决于用户登录、授权范围、账号绑定和当前版本能力，不能假定每次都会返回。按实际返回结果展示；提示 SERVER_API_REQUIRED 时，应按指南改由开发者服务端读取。见用户身份与登录。

授权码过期或已经使用过，能反复重试吗？ ​

授权码短期有效且只能使用一次。过期或已使用时，应重新获取授权码，再交给开发者服务端处理。见用户身份与登录。

请求被限流或连续失败，应该立即重试吗？ ​

不要立即反复重试。上游限流时按建议等待时间退避；Runtime 本地限流时先检查是否存在循环或高频调用。未知错误保留诊断信息，给用户重试或退出的选择。见错误处理。

浏览器里不能选文件、保存或下载怎么办？ ​

SDK 文件能力在 Browser Dev Host 中不提供模拟实现，应在支持对应能力的真实客户端验收。同时检查权限与客户端能力支持；不同平台的支持范围见文件能力与沙箱。

排行榜提交成功，但成绩或排名没有变化，是什么原因？ ​

同一用户在同一榜单只保留更优的成绩，提交相同或更差的分数不会覆盖原记录。超出展示范围时，成绩仍可能已保存；页面应按返回结果展示。其他用户的变化也可能因缓存延迟显示，见云端排行榜。

构建、审核与发布 ​

提交审核或发布前需要检查什么？ ​

确认版本名称、图标和封面完整，在目标客户端验证主要流程，并检查内容、隐私和运行质量要求。具体要求见版本名称与图片和小程序工坊上架规则。

构建提示缺少名称、图标或封面，应该在哪里补？ ​

在项目 package.json 的 heybox 中配置版本名称和项目内图片。图片需要满足尺寸、格式和大小要求；提交审核前替换模板占位图片。见版本名称与图片。

修改名称和图片后，为什么线上仍是旧资料？ ​

名称与图片跟随版本审核，正式发布后才更新线上展示。仅修改本地配置、提交审核，或版本被驳回、撤回，都不会改变当前线上资料。见版本名称与图片。

build、提交审核和正式发布有什么区别？ ​

hb-sdk build 生成本地产物；hb-sdk remote deploy 完成构建、上传和提交审核。默认审核通过后仍需手动发布，普通低风险版本可按规则选择自动发布。见CLI 与本地 mock 调试和小程序工坊上架规则。

上传或提交审核中断了，需要从头创建项目吗？ ​

不需要。先确认失败原因、项目绑定和版本状态，再重新执行提交命令；已验证的文件可复用。部署期间避免其他进程修改构建目录。见CLI 与本地 mock 调试。

升级 SDK 后，AI Agent 仍使用旧用法怎么办？ ​

运行 hb-sdk doctor 检查项目依赖与 Agent Skill 状态，再按指南更新 Skill。见Agent Skill 安装。

问题反馈 ​

如何反馈开发问题或提出建议？ ​

遇到 SDK、开发工具或开放平台的问题，或希望提出功能建议，请在小黑盒 App「设置 → 帮助与反馈 → 小程序工坊」提交反馈。CLI 也支持直接提交私有工单，操作方式见下文。

反馈时请说明实际表现、预期结果和复现步骤，尽量补充 AppID、SDK 版本、设备与客户端版本，以及相关截图或报错日志。提供日志前请删除密码、登录凭证等敏感信息。

提交后在哪里查看进展？别人能看到吗？ ​

提交后进入工单详情，可以查看回复、补充说明，并继续与客服沟通。请保存详情链接，后续使用提交时的账号查看。也可在小黑盒 App「设置 → 帮助与反馈 → 我的反馈」跟进。

开发者反馈是私有客服工单，用户只能查看自己的反馈。

能否直接用 CLI 提交反馈？ ​

先运行 hb-sdk login 登录，再提供完整报错信息提交。新建入口统一为 hb-sdk feedback，不再支持 hb-sdk feedback submit：

bash
hb-sdk feedback --desc "说明遇到的问题和复现步骤" \
  --sdk-version 0.9.1 --platform ios \
  --log ./error.log --screenshot ./error.png \
  --app-id app123

新建反馈必填：至少 5 个字符的问题描述、问题项目实际使用的 SDK 版本、问题发生的平台、非空日志、至少一张截图。示例中的 SDK 版本请替换为问题项目实际使用的版本；描述及运行环境等正文信息合计不能超过 5000 个字符。运行平台通过 --platform 填写 ios、android、windows、macos、linux 或 web；日志统一使用 --log：支持非空 UTF-8 纯文本 .log、ZIP 日志包或文本；文本包装成 .log 后上传，单份上传最大 10 MiB。ZIP 只允许包含非空 UTF-8 .log 文件，最多 50 份，解压后合计最大 20 MiB；日志不占图片额度，正文仅记录日志下载链接；请先脱敏。追加回复必填至少 5 个字符的补充描述，可选附加日志和截图；SDK 版本、平台等环境信息请写入补充描述。

提交成功后，终端会返回工单编号和详情链接。参数见 hb-sdk feedback --help；--screenshot 支持本地图片路径或已上传的 HTTP(S) 图片链接，可重复，图片和 GIF 合计最多 10 张，日志不占图片额度。普通图片单张不超过 20 MiB，GIF 单张不超过 10 MiB。暂不支持视频附件。上传失败时不会继续提交工单。

反馈命令会显示检查文件、上传附件和提交工单的阶段提示，附件按顺序串行上传，全部上传成功后才提交工单；上传失败会提示具体文件和阶段，不继续提交。进度输出到 stderr，--json 的 stdout 只输出最终结果。不保存本地上传进度或提交缓存。提交超时、连接中断或响应不明确时，不自动查询或重试，请先到 App「帮助与反馈 → 我的反馈」核对结果，确认未成功后再重试。

也可查看本人已有的小程序工坊工单，并向原工单补充信息：

bash
hb-sdk feedback list --json
hb-sdk feedback detail 9527 --json
hb-sdk feedback reply 9527 --desc "补充复现步骤" --json

新建前先查看已有工单，同一问题优先追加回复；只是相似时先确认，不自动合并。列表支持 --offset（默认 0）、--limit（默认 20，最多 50 条）；详情和回复只允许访问当前登录账号本人的小程序工坊工单。回复追加到原工单，已解决或关闭的工单不能继续回复。若提示服务端尚未支持工单范围隔离，请稍后重试或通过 App 查看。

如果提示开发者反馈分类尚未开放，请稍后重试。

相关文档 ​

反馈前检查 ​

  • 已记录问题表现、预期结果与复现步骤。
  • 已补充相关版本、设备信息和截图或日志。
  • 提交后已保存工单详情链接。