教程

第 1 步

运行演示

前置要求:Node.js 20.12 及以上 —— 不用克隆、不用安装、不用凭据。

$ npx storepulse demo

演示看板用的是模拟真实团队的示例数据 —— 两个应用,各有 prod·dev 两个变体,覆盖双平台。你今后会见到的所有徽标都在里面: LIVE、50%(灰度发布)、 REVIEW、REJECTED、 draft。更喜欢浏览器? npx storepulse serve --demo 会把同一块看板开在 127.0.0.1:4780。

第 2 步

列出你的应用

$ npx storepulse init

在任意文件夹里都能用 —— 它会创建 storepulse.config.json 和 .env 模板(已有的文件绝不会被覆盖),并把凭据文件加进 .gitignore。在本仓库的克隆里, cp storepulse.config.example.json storepulse.config.json 效果相同。接着打开 storepulse.config.json,列出你的应用:

第 3 步

Apple —— App Store Connect API 密钥

从这里开始,要填的是 storepulse init 生成的 .env(仓库克隆里则用 cp .env.example .env)。

1. App Store Connect → 用户和访问(Users and Access) → 集成(Integrations) → App Store Connect API。
2. 在团队密钥(Team Keys)下点 ＋。角色建议选 Developer —— 对 storepulse 的读取来说已经足够。App Manager 也能用,但密钥一旦泄露,提交应用、改动元数据的权限也会一并流出,按最小权限原则来更稳妥。
3. 下载 .p8 文件。 Apple 只允许下载一次 —— 请妥善保管(storepulse init 已把它加入 git 忽略)。这把密钥能在其角色允许的范围内执行写操作,一旦泄露,请立即到 App Store Connect 吊销(revoke)。
4. 填好三个值:

ASC_KEY_ID=ABC123DEFG          # 密钥的 "Key ID" 列
ASC_ISSUER_ID=xxxxxxxx-...     # 页面顶部的 "Issuer ID"
ASC_PRIVATE_KEY_PATH=./AuthKey_ABC123DEFG.p8

控制台界面时常变动 —— 如果菜单位置对不上,请按照 Apple 官方指南 Creating API Keys for App Store Connect API 操作。

第 4 步

Google —— Play 服务账号

1. 在 Google Cloud Console 选择(或创建)一个项目,启用 Google Play Android Developer API。
2. IAM 和管理 → 服务账号 → 创建一个(无需任何角色)→ 密钥标签页 → 添加密钥 → JSON。
3. Play Console → 用户和权限 → 邀请新用户 → 粘贴服务账号邮箱 (…@…iam.gserviceaccount.com)→ 为你的应用授予查看应用信息(View app information)权限。 只授予这一项 —— 千万不要授予任何发布(Release)权限; storepulse 用不到,这样即使密钥泄露也只停留在只读。
4. 让 .env 指向该 JSON:

PLAY_SERVICE_ACCOUNT_PATH=./service-account.json

如果控制台布局有变,Google 官方的 Google Play Developer API 入门指南覆盖了同样的步骤。

第 5 步

运行

$ npx storepulse

你的真实看板就出现了(在仓库克隆里,pnpm status 效果相同)。凭据有问题的行只会在原地显示错误, 不会遮住看板的其余部分。

第 6 步

在浏览器里看

$ npx storepulse serve

打开 http://127.0.0.1:4780, 看板就会以自动刷新的 Web 看板呈现。如果配置使用可选的 group 字段,选择器一次显示一个分组;所有应用都没有分组时 则会隐藏。每张应用卡片分开显示 iOS 和 Android 行、最新包与发布渠道, OS 标签可筛选平台行。点击任意一行即可展开详情面板 —— 发布说明全文、 日期和 TestFlight 到期倒计时。点击状态徽标 (而不是整行)会弹出解释该状态含义的对话框,顶栏的 EN/KO 切换器 还能切换界面语言(选择会记在浏览器里)。还没配好 凭据?npx storepulse serve --demo 也行。默认只绑定 127.0.0.1 —— 看板上可能出现尚未发布的版本号, 留在本机更稳妥。

第 7 步 —— 可选

关联 Expo(EAS)构建

在用 Expo 发版?往 .env 里加一个访问令牌 (在 expo.dev → Access tokens 创建;组织账号建议用 View Only 机器人令牌 —— storepulse 只读取构建和提交),再给 storepulse.config.json 里的 Expo 应用条目加上 easProjectId(app.json → extra.eas.projectId):

EAS_TOKEN=...

快照(JSON)和 Web 看板的详情面板就会显示商店里的每个版本出自哪个 EAS 构建 —— git 提交、构建配置文件、提交状态(终端看板保持摘要)。npx storepulse doctor 的 [5] 一节还会逐步检查整条 EAS 链路。

CI —— 可选

按发布状态让构建失败

$ npx storepulse check --fail-on rejected,halted

可指定标准化状态 live、rollout、 in-review、pending、rejected、 halted、draft 或 unknown。 退出码 0 表示无匹配,1 表示策略违规, 2 表示参数错误或采集失败。需要机器可读输出时加 --format json;无需凭据试用时加 --demo。

问题排查

哪里不对劲时

先运行 npx storepulse doctor —— 下面这些原因,它大多能自动诊断出来,每个失败项还会给出一行解决办法。

还是卡住了?开个 issue —— 把看板上那行错误原样贴上来就行。