第一次上 Google Play,最麻煩的不是寫 App
LilyScore 在我的手機上能正常開啟、能讀 PDF、能播伴奏時,我以為最難的部分已經過了。接下來大概就是把 App 打包、拖進 Google Play Console,等審核而已。
真的開始上架後,我才發現,能跑的 App 跟能上架的 App 中間,還隔著 application ID、簽章金鑰、商店資料、內容申報、測試軌與發布權限。這些設定散在本機、Play Console、Google Cloud 和 GitHub,每一項單獨看都不難,第一次卻會在同一段時間一起出現。
這篇把 LilyScore 從 Flutter 專案走到 Google Play 正式版的順序完整記下來。前半段是第一次上架一定會碰到的工作,後半段才是 GitHub Actions 自動發版;如果只想手動上傳,做到測試軌與正式版就可以停。
上架流程總覽
我最後走過的順序如下。第一次上架的主線走到正式版就結束,自動發版是手動流程成功後才加上去的。LilyScore 的自動化終點只有 closed testing,production 仍是 Play Console 裡的人工動作。
graph TD
app[App 可在實機執行] --> identity[固定 App 永久識別字<br/>application ID]
identity --> key[建立上傳金鑰]
key --> aab[簽出第一個上傳檔案<br/>AAB]
aab --> console[Play Console 建立 App]
console --> listing[商店資料與內容申報]
listing --> first[手動上傳第一版]
first --> test[測試軌與測試者]
test --> production[申請並發布正式版]
first --> api[選用:設定 Play API]
api --> ci[選用:自動發版<br/>GitHub Actions]
ci --> test
整條流程牽涉五個地方。把它們分開看,遇到錯誤時會比較容易知道該去哪裡找。
| 場所 | 放什麼 | 大約多久處理一次 |
|---|---|---|
| 本機 | Flutter 專案、上傳金鑰、金鑰設定檔 | 每個 App 設定一次,金鑰長期保存 |
| Play Console | App、商店資料、內容申報、測試軌、正式軌 | 第一次設定最多,之後每版確認 |
| Google Cloud | Play API、服務帳號 | 只有自動上傳才需要,設定一次 |
| GitHub Secrets | 自動發版的簽章資料與 Play 憑證 | 只有自動上傳才需要,憑證輪替時更新 |
| GitHub Actions | 測試、建置、建立 Release、上傳測試軌 | 只有自動上傳才需要,每次發版執行 |
準備 Android 發布檔
固定 App 識別字
applicationId 是 Google Play 用來辨認 App 的永久識別字,格式通常長得像 com.example.myapp。第一個 AAB 上傳到 Play 後若改掉,Play 會把它視為另一個 App,原本的使用者也收不到更新,因此要在上傳前定案。Configure the app module
Flutter 專案可以在 android/app/build.gradle.kts 的 defaultConfig 找到它。還要檢查 CI 上傳步驟使用的 packageName 是否完全相同,大小寫也不要自行改。LilyScore 用的是 com.CalmKoala.LilyScore,這是專案選擇,不是 Google 要求的命名格式。
建立簽章金鑰
Android App 發布時會遇到兩把金鑰。上傳金鑰(upload key)由開發者保管,用來簽署送進 Play Console 的 AAB;應用程式簽署金鑰(app signing key)由 Play App Signing 保管,Google 會用它簽署真正送到使用者裝置上的 APK。上傳金鑰遺失或外洩時可以申請重設,但仍應把金鑰檔與密碼備份好。Sign your app
Flutter 官方文件提供用 keytool 建立金鑰的方式。下面是 LilyScore 在專案根目錄使用的路徑,金鑰會放在已被 .gitignore 排除的 android/app/;建立時輸入的密碼要直接存進密碼管理器。
1 | keytool -genkey -v -keystore android/app/upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload |
如果終端機顯示找不到 keytool,先執行 flutter doctor -v,找到輸出裡的 Java binary at。keytool 和 java 會在同一個 bin 目錄,可以用它的完整路徑重新執行上面的指令。Android Studio 內附的 JDK 通常已經包含它,不需要另外下載來路不明的工具。
接著建立 android/key.properties,讓 Gradle 知道 release build 要使用哪一把金鑰。
1 | storePassword=<keystore 的密碼> |
這組 storeFile 寫法成立,是因為 LilyScore 把金鑰放在 android/app/,而 Gradle 的 App module 也從這裡解析路徑。若你把金鑰放在其他位置,兩邊要一起調整。key.properties、*.jks 與 *.keystore 都要放進 .gitignore。金鑰檔轉成 base64 也只是編碼,不會因此變安全;base64 內容同樣不能放進 repo、對話紀錄或公開文件。
最後還要在 android/app/build.gradle.kts 載入 key.properties,建立 release signing config,並讓 release build type 使用它。下面保留 LilyScore 實際需要的部分,其他 Flutter 與 Android 設定不用為了這段刪掉。
1 | import java.io.FileInputStream |
這裡先檢查 key.properties 是否存在,是為了讓沒有私密金鑰的新 clone 仍能執行 debug build,同時讓 release build 在缺少設定時直接報錯。Flutter 新專案的 release build type 可能暫時沿用 debug key,接上這段時要把原本的 debug signing 設定移除。如果這段交給 AI 修改,我會要求它說明改了哪個檔案、release build type 最後指向哪個 signing config,再由自己檢查 diff。這樣比只問「幫我把簽章接好」更容易知道它有沒有偷偷沿用 debug key。
建立 AAB
Android App Bundle(AAB)是送進 Google Play 的上傳檔案,Play 會再依使用者的裝置產生合適的 APK。Flutter 的 pubspec.yaml 會用 version: x.y.z+N 同時表示兩個值。前面的 x.y.z 會成為使用者看到的 versionName,加號後面的 N 會成為 Play 判斷新舊版本的 versionCode。每次上傳都要使用更大的 versionCode,已經上傳過的數字不能重複使用。Version your app
簽章設定接好後,在專案根目錄執行:
1 | flutter build appbundle --release |
Flutter 會在 build/app/outputs/bundle/release/ 產生 AAB。本機的完成標誌是 release AAB 成功出現,而且 build.gradle.kts 的 release build type 指向前面建立的 release signing config;路徑、密碼或 alias 有任何一項對不上,建置會在這裡失敗。這時也要再檢查 applicationId 已經定案,以及 versionCode 沒有用過。Flutter 官方的 Android 發布指南整理了 keystore、Gradle 與 AAB 的完整設定方式。Build and release an Android app
設定 Play Console
建立商店頁
Play Console 的「建立應用程式」會要求預設語言、App 名稱、App 或遊戲、免費或付費、聯絡信箱與政策聲明。建立完成後,Dashboard 會列出送審前仍缺少的工作。Create and set up your app
我會在開始填 Console 之前先備好下面這些材料,避免每完成一格又回頭找圖。
| 材料 | 用途或檢查方式 |
|---|---|
| App 名稱、簡短說明、完整說明 | 名稱與說明要和實際功能一致 |
| 512×512 App 圖示 | Play 商店列表與搜尋結果使用 |
| 1024×500 主題圖片 | 商店刊登資訊使用 |
| 手機與平板截圖 | 依實際支援裝置準備,不要放尚未推出的畫面 |
| 聯絡信箱與網站 | 給使用者聯絡,隱私權政策也需要公開網址 |
| 隱私權政策 | 內容要對得上 App 與使用的第三方 SDK |
| 測試者名單 | 封閉測試使用,名單內的人仍要自行 opt-in |
商店素材的尺寸與數量可能調整,正式製作前可以回到 Add preview assets to showcase your app 檢查當下要求。
填寫內容申報
App content 不是固定十二題。Play Console 會依 App 類型、權限、目標地區與功能顯示需要填寫的申報,常見項目包含隱私權政策、廣告、審查人員如何存取 App、目標對象、內容分級、Data safety 與敏感權限。每一項都要按照 App 實際行為填寫,不能只照另一個 App 的答案複製。Prepare your app for review
Data safety 特別容易和程式實作脫節。即使自己的程式沒有主動收集資料,分析、登入、付款或雲端 SDK 仍可能處理使用者資料,所以填表前要把相依套件一起檢查。AI 可以協助列出 Android manifest 的權限、專案裡使用的 SDK,以及程式可能把哪些資料送到網路,但表單答案仍要由自己對照實際行為與第三方文件確認,不能把 AI 的推測直接送出。送審前我會以 Dashboard 沒有未完成的必要項目作為完成標誌。
上傳第一版
Google Play Developer Publishing API 的 Edits 文件目前仍寫著,API 只能修改至少已有一個套件上傳的 App,因此第一個套件要先透過 Play Console 上傳。Edits LilyScore 的第一顆 AAB 也走手動流程,等 Console 已經認得這個 App 後,後續版本才交給 GitHub Actions。
第一次手動上傳可以照這個順序走:
- 打開 Play Console 並選擇 App,進入「Test and release」下的 internal testing 或 closed testing。
- 建立一個 release,第一次使用 AAB 時依畫面啟用 Play App Signing。
- 上傳前面產生的 release AAB,等 Console 完成處理並顯示新的
versionCode。 - 填寫這版的名稱與更新說明,處理 Console 顯示的錯誤或警告。
- 儲存後依畫面上的按鈕 rollout 或發布;是否進入審查,要看 Dashboard 與該軌道的狀態。
- 到測試者頁面建立 email 名單或 Google Group,取得 opt-in 連結並傳給測試者。
對新 App 來說,先用 internal testing 驗證安裝速度最快,但它不會累積新個人帳號需要的 12 人、14 天 closed testing 資格。受到正式版測試門檻限制的帳號,還要另外建立 closed testing;opt-in 指的是測試者打開加入連結、主動成為測試成員,不是開發者把 email 填進名單就完成。Prepare and roll out a release
「測試者 email 已在名單裡」還不算完成。至少要找一位測試者打開 opt-in 連結、加入測試,再從 Google Play 安裝成功;做到這裡,才代表商店資料、測試軌、簽章與發布設定真的接起來。
測試內購
如果 App 有內購,要先讓包含 Google Play Billing Library 的版本進入任一測試軌,再到 Play Console 建立商品。商品 ID 必須和程式內查詢的字串相同;建立後也要完成定價並啟用。做到商品在 Console 顯示為有效,而且 license tester 能看到測試付款工具,才算把內購測試接通。
測試軌的測試者和 license tester 是兩份設定,兩者用途不同,同一個 Google 帳號可以同時存在於兩邊。
| 身分 | 用途 | 容易搞錯的地方 |
|---|---|---|
| 測試軌測試者 | 安裝 internal 或 closed testing 的版本 | 加入名單後仍要點 opt-in |
| License tester | 使用測試付款工具驗證內購 | 只有測試軌身分仍可能被真實扣款 |
如果 App 有內購,測試帳號要加到 Play Console 的 license testing 名單。裝置有多個 Google 帳號時,通常由下載 App 的帳號進行付款,因此測試前要先確認購買面板顯示的是哪一個帳號。Test your Google Play Billing Library integration
封閉測試門檻
截至 2026 年 8 月 23 日,2023 年 11 月 13 日後建立的個人開發者帳號,在取得正式版權限前,需要讓至少 12 名測試者在 closed test 持續 opt-in 14 天。時間達標後還要從 Dashboard 申請 production access,回答測試過程、收到的回饋與正式發布準備;完成測試不等於自動取得正式版權限。App testing requirements for new personal developer accounts
取得 production access 後,可以建立正式版 release,也可以把測試軌已驗證的版本升到 production。LilyScore 的 CI 只負責把版本送進封閉測試軌,正式發布仍保留在 Play Console 手動操作,避免測試版因為打了一個 tag 就直接推給所有使用者。
發布正式版
Production access 核准後,我會繼續用測試過的同一顆 AAB,不重新建一個相同 versionCode 的檔案。實際選單名稱可能隨 Console 改版,但目前可以照下面的順序操作。Prepare and roll out a release
- 在 Play Console 選擇 App,進入「Test and release」下的 Production。
- 點「Create new release」。如果按鈕不能使用,先回 Dashboard 完成它列出的設定或申報。
- 從 artifact library 選擇已經在測試軌驗證過的 AAB;若這版尚未上傳,也可以在這裡上傳新的 release AAB。
- 確認
versionCode、版本名稱與更新說明,並檢查要發布的國家、地區和定價設定。 - 處理頁面上的錯誤。警告不一定會阻擋發布,但仍要逐項確認原因,再進入 release review。
- 確認摘要後開始 rollout to production。第一次正式 rollout 通過審查後,會提供給所選國家與地區的使用者。
- 回到 Publishing overview 或 Latest releases 追蹤狀態。除了看到 Production release,也要實際打開選定地區的商店頁,確認頁面能搜尋或透過連結開啟,並從 Google Play 安裝正式版。
對我來說,按下 rollout 還不算結束。Play Console 顯示正式版已發布、商店頁可開啟,而且安裝後跑得過主要流程,這一版才真正完成。
設定自動發版
自動發版不是第一次上架的前置條件。如果一年只更新幾次,手動簽 AAB 再上傳也能完成工作;LilyScore 會接 CI,是因為我想把測試、簽章、GitHub Release 與封閉測試上傳固定成同一條流程。
授權 GitHub Actions
CI 要對 Play 上傳,會跨 Google Cloud 與 Play Console 做一次設定。
- 在 Google Cloud 建立或選擇一個 project。
- 啟用 Google Play Android Developer API。
- 建立專用 service account。
- 回到 Play Console 的「使用者和權限」,邀請 service account 的 email。
- 只授予這個 App 與目標測試軌需要的發布權限。LilyScore 使用「發布應用程式至測試群組」與「管理測試群組並編輯測試人員名單」,其他 App 應依 workflow 真正執行的動作縮減。
服務帳號在 Google Cloud 建立,能不能發布 App 則由 Play Console 的權限決定。少做任何一邊,CI 都無法完成上傳。完成時,Play Console 的使用者清單應看得到這個 service account,而且指定 App 的權限已儲存。Getting Started — Google Play Developer API
LilyScore 使用 service account JSON 存進 GitHub Secret,設定快,但它是長期有效的憑證,外洩後等同別人拿到 CI 的發布身分。
設定 GitHub Secrets
GitHub Actions 需要四項簽章資料與一項 Play API 憑證。Secret 名稱可以公開,值不行。
| GitHub Secret | 內容 | Workflow 裡的用途 |
|---|---|---|
ANDROID_KEYSTORE_BASE64 |
上傳金鑰檔的 base64 | 執行時還原 upload-keystore.jks |
ANDROID_KEYSTORE_PASSWORD |
keystore 密碼 | 重建 key.properties |
ANDROID_KEY_ALIAS |
key alias | 重建 key.properties |
ANDROID_KEY_PASSWORD |
key 密碼 | 重建 key.properties |
PLAY_SERVICE_ACCOUNT_JSON |
service account JSON 全文 | 呼叫 Play API |
GitHub Secrets 只有在 workflow 顯式引用時才會提供給工作。Log 的遮蔽機制也不是外洩保證,因此 workflow 不應印出 Secret、解碼後的金鑰或完整環境變數。Secrets
自動發版流程
LilyScore 的 release.yml 會在收到 v* tag 後依序執行:
- 安裝指定版本的 Flutter 與 JDK。
- 執行
flutter analyze與flutter test。 - 從 Secrets 還原 keystore 與
key.properties。 - 建立簽章好的 AAB,以及方便直接安裝測試的 arm64 APK。
- 建立 GitHub Release 並附上兩份產物。
- 正常版 tag 才把 AAB 上傳到 Play 封閉測試軌;帶 pre-release 字尾的 tag 不上 Play。
Google Play API 裡的軌道名稱不一定等於 Console 畫面上的顯示文字。官方文件目前將 internal、open testing 與 production 的預設 API 名稱列為 qa、beta、production,closed testing 則可以使用自訂名稱。APKs and Tracks LilyScore 的 closed track 剛好叫 alpha,這個值不能直接複製到其他 App。
LilyScore 第一次讓 CI 上傳時遇到 403。服務帳號建好了,Play Console 權限也給了,最後才發現 Google Cloud 裡的 Play Developer API 沒有啟用。錯誤看起來像程式或權限壞掉,實際上只是另一個 Console 少按了一次開關。
發布後續版本
沒有接 CI 時,後續更新就是第一次手動上傳的縮短版。先更新 versionName 與 versionCode,執行測試並建立簽章 AAB,再到 Play Console 的目標軌道建立 release、上傳 AAB、填更新說明,最後 rollout。測試完成後要上正式版,則依前面的 production 步驟選擇同一顆 AAB。只要每次留下版本號、更新說明與測試結果,手動發版也能保有完整紀錄。
LilyScore 把這條路接上自動化後,正式封測版會從一行指令開始:
1 | scripts\release.ps1 -Version 2.3.0 |
腳本會檢查目前在 main、工作區沒有已追蹤的未提交修改、本機沒有落後 origin/main、tag 尚未存在,而且 flutter analyze 通過。接著它更新 pubspec.yaml 的版本名稱、自動增加 build number、產生 Play 更新說明,最後建立 commit 與 tag,再 push 讓 CI 接手。
我另外留了三個參數,避免所有版本都只能走同一條路。
| 用法 | 作用 |
|---|---|
-Notes "文字" |
覆寫自動產生的 Play 更新說明 |
-NoPush |
停在本機 commit 與 tag,檢查完再手動 push |
-Pre alpha.1 |
建立 GitHub pre-release 與安裝檔,不上傳 Play |
Play 的「這個版本的新功能」會從上一個沒有 pre-release 字尾的 tag 開始,只取 feat: 與 fix: commit 標題;GitHub Release 則從上一個 v* tag 開始列出所有 commit。兩邊面向的讀者不同,所以來源範圍也不同。每次正常版最後仍要確認 Actions 全綠、Play Console 出現新的 versionCode,並在測試軌實際安裝一次。
正式版不由 LilyScore 的 CI 自動推送。封閉測試確認沒問題後,我會回到 Play Console,把同一顆 AAB 升到 production,再檢查送審狀態與最終商店頁。
常見錯誤
| 症狀 | 優先檢查 | 常見原因 |
|---|---|---|
終端機找不到 keytool |
flutter doctor -v 的 Java 路徑 |
JDK 已安裝,但它的 bin 不在 PATH |
Package not found |
Play Console、packageName |
App 尚未建立、第一個套件尚未上傳,或 application ID 不一致 |
API 呼叫回傳 403 |
Google Cloud、Play Console | Play Developer API 未啟用,或 service account 沒有目標 App/軌道權限 |
| Play 拒收版本 | pubspec.yaml、Console 版本紀錄 |
versionCode 已使用或沒有增加 |
| Workflow 找不到軌道 | Play Console 與 API 回傳值 | 把顯示名稱當成 API track name |
| CI 簽章失敗 | 四個 Android Secrets | keystore base64、密碼、alias 或還原路徑不一致 |
| 更新卡在送審前 | Play Console Dashboard | 商店資料、App content、定價或政策申報仍有缺項 |
| 測試內購出現真實卡片 | License testing、裝置帳號 | 測試者只加入測試軌,或付款帳號不是 license tester |
遇到錯誤時,我會按照「本機 → GitHub → Google Cloud → Play Console」逐段檢查。這個順序不保證每次最快,但至少不會看到 403 就立刻重寫發版腳本。
上架檢查清單
一次性設定
- application ID 已定案,Gradle 與 CI 的
packageName相同 - upload keystore 已建立,金鑰與密碼分開備份
-
key.properties、*.jks已被.gitignore擋住 - release AAB 能在本機成功建置
- Play Console App 已建立
- 商店素材、聯絡資料與隱私權政策已準備
- Dashboard 要求的 App content 已完成
- 第一個 AAB 已手動送進測試軌
- 測試者已 opt-in,並從 Google Play 安裝成功
- 帳號若受測試門檻限制,closed test 已提早開始
- production access 已申請
- production access 已核准
- 正式版已送審,並確認最終發布狀態
自動發版設定
- Google Play Android Developer API 已啟用
- service account 已建立並加入 Play Console
- 權限只涵蓋指定 App 與需要的測試軌
- CI 簽章資料與 Play 憑證已放入 Secrets
- workflow 的
packageName與 track name 已核對 - CI 成功建置、簽章並上傳一個測試版
每版檢查
-
versionCode比 Play 上既有版本大 - 使用者看得懂這版更新說明
- analyze 與 test 通過
- AAB 使用 release key 簽章
- GitHub Release 與 Play 測試軌都出現預期版本
- 從 Play 安裝並跑過主要流程
- 要上正式版時,人工確認升軌與送審內容
我還會在私有專案文件或密碼管理器的 metadata 欄位留下 application ID、GCP project 名稱、service account email、closed track 的 API 名稱、金鑰備份位置,以及最後一次查核 Play 政策的日期。公開文件只記欄位名稱與存放位置,不貼真實 project number、email 或檔案路徑。這些紀錄能省下半年後重新在四個 Console 裡找路的時間。
LilyScore 終於上架後,我最想先忘掉的就是這些設定。偏偏它們又是下一個 App 最容易重踩的地方,所以這次乾脆把完成標誌、Secrets 和排錯順序一起記下來。
希望下次看到 403 時,我能先想到「少了哪個地方的設定」,不要又先懷疑自己把程式寫壞了。啊啊啊~