教學

步驟 1

安裝並執行展示

前置需求:Node.js 20.12 以上、pnpm 9 以上。

$ git clone https://github.com/dioKR/storepulse.git
$ cd storepulse
$ pnpm install
$ pnpm demo

展示看板用的是仿照真實團隊的範例資料 —— 兩個 App,各有 prod·dev 兩種變體,橫跨雙平台。之後會見到的所有徽章都在裡面: LIVE、50%(逐步發布)、 REVIEW、REJECTED、 draft。

步驟 2

列出你的 App

$ npx storepulse init

在任何資料夾裡都能用 —— 它會建立 storepulse.config.json 與 .env 範本(已存在的檔案絕不會被覆寫),並把憑證檔案加進 .gitignore。若你是 clone 本儲存庫來開發, cp storepulse.config.example.json storepulse.config.json 效果相同。接著打開 storepulse.config.json,列出你的 App:

步驟 3

Apple —— App Store Connect API 金鑰

從這裡開始,要填的是 storepulse init 產生的 .env(儲存庫 clone 裡則用 cp .env.example .env)。

1. App Store Connect → 使用者與存取權(Users and Access) → 整合(Integrations) → App Store Connect API。
2. 在團隊金鑰(Team Keys)按 ＋。角色建議選 Developer —— 對 storepulse 的讀取來說已經足夠。App Manager 也能用,但金鑰一旦外洩,提交 App、更動中繼資料的權限也會跟著流出,依最小權限原則比較穩妥。
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)→ 為你的 App 授予檢視應用程式資訊(View app information)權限。 只授予這一項 —— 千萬不要授予任何發布(Release)權限; storepulse 用不到,這樣即使金鑰外洩也只停留在唯讀。
4. 讓 .env 指向該 JSON:

PLAY_SERVICE_ACCOUNT_PATH=./service-account.json

如果主控台版面有變,Google 官方的 Google Play Developer API 入門指南涵蓋了同樣的步驟。

步驟 5

執行

$ npx storepulse

你的真實看板就會出現(在儲存庫的 clone 裡,pnpm status 效果相同)。憑證有問題的列只會在原位顯示錯誤, 不會遮住看板其餘部分。

步驟 6

用瀏覽器看

$ npx storepulse serve

打開 http://127.0.0.1:4780, 同一塊看板就以同樣的設計出現在 Web 儀表板裡,並自動重新整理。 點選任一列就會展開詳細面板 —— 版本說明全文、日期與 TestFlight 到期倒數。上方的標籤還能依 OS 與群組篩選看板。點一下狀態徽章 (而不是整列)會跳出解釋該狀態意義的對話方塊,頂欄的 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 App 項目加上 easProjectId(app.json → extra.eas.projectId):

EAS_TOKEN=...

快照(JSON)和 Web 儀表板的詳細面板就會顯示商店裡的每個版本出自哪個 EAS 建置 —— git commit、建置設定檔、送審狀態(終端機看板維持摘要)。npx storepulse doctor 的 [5] 一節還會逐步檢查整條 EAS 鏈路。

疑難排解

哪裡不對勁時

先執行 npx storepulse doctor —— 下面這些原因,它大多能自動診斷出來,每個失敗項目還會給出一行解決辦法。

還是卡住了?開一個 issue —— 把看板上那行錯誤原封不動貼上來就行。