Jak utworzyć keystore Androida (przewodnik krok po kroku)

Keystore to zaszyfrowany plik zawierający parę kluczy prywatny/publiczny używaną do podpisywania aplikacji. Google Play wymaga, aby każdy przesyłany plik AAB miał ważny podpis; niepodpisany lub błędnie podpisany pakiet zostaje odrzucony przez Play Console już podczas przesyłania.

Flutter i Android Studio automatycznie generują „debug keystore" do programowania lokalnego; ma on stałe hasło, służy wyłącznie do testów na własnym urządzeniu i żaden sklep go nie akceptuje. Pakiet przesyłany do sklepu musi być podpisany kluczem keystore typu „release" lub „upload", który generujesz samodzielnie.

Każda kolejna aktualizacja tej samej aplikacji musi być podpisana tym samym kluczem (lub łańcuchem podpisów uznawanym przez Google); w przeciwnym razie Play Console odrzuci aktualizację jako „podpisaną innym certyfikatem", zmuszając użytkowników do odinstalowania i ponownej instalacji. Dlatego plik keystore jest trwałą częścią tożsamości Twojej aplikacji.

keytool to narzędzie wiersza poleceń dołączone do Java Development Kit (JDK); ponieważ instalacja Fluttera lub Android Studio zawiera już JDK, zwykle nie trzeba instalować niczego osobno. Standardowe polecenie zalecane w oficjalnej dokumentacji Fluttera to: keytool -genkey -v -keystore upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload. Flaga -storetype JKS ma tu znaczenie: od Javy 9 domyślnym typem magazynu w keytool jest PKCS12, więc bez tej flagi powstały plik miałby rozszerzenie .jks, ale faktycznie zawierałby dane w formacie PKCS12.

-keyalg RSA -keysize 2048 ustawia algorytm i długość klucza, -validity 10000 utrzymuje ważność klucza przez około 27 lat, a -alias upload to krótka nazwa nadawana kluczowi, której użyjesz ponownie w key.properties. Po uruchomieniu polecenia zostaniesz kolejno poproszony o hasło magazynu (store password), hasło klucza (key password) oraz dane imienia/organizacji.

Na macOS i Linuksie keytool działa bezpośrednio z terminala, jeśli JDK znajduje się w PATH. W Windows uruchom najpierw flutter doctor -v, aby sprawdzić, które dokładnie JDK jest używane, i odszukaj w wyniku wiersz „Java binary at:"; keytool znajduje się w folderze bin tego katalogu (jeśli JAVA_HOME nie jest ustawione lub masz zainstalowane więcej niż jedno JDK, założenie ścieżki „%JAVA_HOME%\bin\keytool" może wskazywać na niewłaściwe JDK). Dostosuj ścieżkę pliku w parametrze -keystore do własnego katalogu użytkownika i zanotuj katalog, z którego uruchomiono polecenie — ta ścieżka będzie potrzebna ponownie w następnym kroku.

Utwórz plik o nazwie key.properties w katalogu android/ i dodaj wiersze storePassword, keyPassword, keyAlias oraz storeFile (pełna ścieżka do pliku keystore). Ten plik jest zwykłym tekstem i jawnie zawiera Twoje hasła, więc nigdy nie może trafić do systemu kontroli wersji — jako pierwszy krok dodaj linię key.properties do .gitignore.

W pliku android/app/build.gradle.kts (aktualny DSL Kotlin) odczytujesz ten plik i definiujesz blok signingConfigs.release, w którym keyAlias, keyPassword, storeFile i storePassword pochodzą z key.properties. Następnie przypisujesz signingConfig = signingConfigs.getByName("release") do typu builda release, dzięki czemu każdy wygenerowany pakiet release jest podpisywany tym kluczem.

Jeśli włączone jest zmniejszanie kodu R8/ProGuard (isMinifyEnabled=true), przetestuj podpisany pakiet release na prawdziwym urządzeniu przed przesłaniem go do sklepu; niektóre pakiety korzystające z refleksji są podatne na zmniejszanie i ulegają awarii wyłącznie w buildzie release. Nie ma to związku z samym podpisywaniem, ale to częsty błąd zapominany na tym samym etapie.

Od 2021 roku Google wymaga Play App Signing dla nowych aplikacji i opcja rezygnacji już nie istnieje. Ten model obejmuje dwa odrębne klucze: „upload key", który generujesz za pomocą keytool i używasz do podpisywania każdego AAB, oraz „app signing key", który Google przechowuje we własnej bezpiecznej infrastrukturze i którym nadaje ostateczny podpis pakietowi dystrybuowanemu użytkownikom. Nigdy sam nie widzisz ani nie posiadasz app signing key.

Jeśli zgubisz swój upload key (plik lub jego hasła), ale masz włączone Play App Signing, jest wyjście: w Play Console przejdź do Protected with Play > Play Store protection > Manage Play app signing, a następnie otwórz żądanie „Request upload key reset" w sekcji „Upload Key Certificate". Proces wygląda tak: najpierw generujesz nowy keystore upload za pomocą keytool, następnie eksportujesz jego certyfikat do formatu PEM poleceniem keytool -export -rfc -keystore upload-keystore.jks -alias upload -file upload_certificate.pem, po czym przesyłasz ten plik PEM do Play Console wraz z notatką wyjaśniającą powód resetu. Gdy Google przeanalizuje i zatwierdzi żądanie, nowy upload key staje się aktywny; ponieważ właściwy klucz podpisujący nigdy nie opuścił rąk Google, tożsamość aplikacji w sklepie, recenzje i liczba instalacji pozostają nienaruszone.

Jeśli nigdy nie zapisałeś się do Play App Signing — co jest typowe dla starszych aplikacji opublikowanych, zanim stało się to obowiązkowe — i zgubisz swój jedyny klucz podpisujący, nie ma odwrotu: nigdy nie prześlesz kolejnej aktualizacji tej aplikacji. Jedyną opcją jest otwarcie zupełnie nowego wpisu pod nowym applicationId, co oznacza utratę dotychczasowych recenzji, liczby instalacji i pozycji w wyszukiwaniu.

Trzymanie pliku keystore na jednym lokalnym dysku jest ryzykowne: awaria dysku, ponowne sformatowanie lub wymiana komputera mogą trwale go zniszczyć. Miej co najmniej jedną zaszyfrowaną kopię zapasową (dysk zewnętrzny, zaszyfrowana chmura) i nigdy nie dodawaj tego pliku do repozytorium projektu — podobnie jak key.properties, plik keystore również powinien znaleźć się w .gitignore.

Przechowuj hasło magazynu i hasło klucza w menedżerze haseł oraz zapisz też nazwę aliasu; bez tych trzech elementów sam plik jest bezużyteczny. Nigdy nie udostępniaj haseł jako zwykłego tekstu przez e-mail czy komunikatory; jeśli pracujesz w zespole, ogranicz dostęp tylko do osób, które naprawdę go potrzebują.

Skarbiec Keystore Vibeloy przechowuje Twój plik keystore i hasła w szyfrowaniu end-to-end; zamiast trzymać plik jako jedyną lokalną kopię, możesz bezpiecznie przechowywać go w skarbcu powiązanym z kontem, dostępnym z dowolnego urządzenia. To funkcja premium Vibeloy.