Voltar

PASSO A PASSO LINEAR

Do ZIP até o AAB na Play Store

Faça um passo de cada vez, na ordem. Não pule. Cada passo termina mostrando o que você deve estar vendo na tela antes de seguir pro próximo.

⚙️ Personalize os comandos abaixo

Preencha estes 3 campos e todos os comandos do guia vão aparecer prontos pra copiar e colar — sem precisar editar nada.

Veja em C:\Users\

No Mac rode whoami

Mesmo nome do ZIP baixado

Checklist de pré-requisitos (antes de começar)

Confirme cada item abaixo antes do Passo 1. Se faltar algum, o setup vai falhar no meio e você vai perder tempo.

  • Node.js 20 ou superior instalado. Teste no terminal: node -v deve mostrar v20.x ou maior. Não tem? Baixe em nodejs.org (versão LTS).
  • JDK 17 instalado (vem junto com o Android Studio na pasta jbr/). Teste: java -version deve mostrar 17.x.
  • Android Studio instalado (versão Hedgehog 2023.1.1 ou mais recente). Baixe em developer.android.com/studio.
  • Android SDK Platform 34 + Build Tools 34.0.0. No Android Studio → More Actions → SDK Manager e marque ambos.
  • Internet estável + ~5 GB livres em disco (Gradle baixa muita coisa na primeira vez).
  • ZIP do app já baixado em Downloads (gerado no painel deste site).
Não tem certeza se Node ou Java estão instalados? Abra o terminal e cole os comandos abaixo. Se algum der erro de "comando não reconhecido" / "command not found", instale antes de seguir pro Passo 1.
Verifica Node
node -v
Verifica Java
java -version

Erro "não é reconhecido como comando"? Faça isto:

Se ao rodar qualquer comando o terminal retornar algo como:

O termo 'setup.bat' não é reconhecido como nome de cmdlet, função, arquivo de script ou programa operável.

'npm' is not recognized as an internal or external command.

zsh: command not found: cap

Identifique qual dos 3 casos é o seu e siga a ação exata:

🔵 Caso 1 — Erro com setup.bat no PowerShell (fundo azul, prompt PS C:\...)

O PowerShell exige .\ antes do nome do arquivo, mesmo estando na pasta certa. Cole exatamente assim:

No PowerShell
.\setup.bat

Ainda mais simples: feche o PowerShell, abra o CMD em vez disso (no Explorador, barra de endereço → digite cmd → Enter). No CMD funciona setup.bat sem o .\.

🟢 Caso 2 — Erro com npm, node ou npx

Significa que o Node.js não está instalado ou não foi adicionado ao PATH. Baixe e instale a versão LTS:

nodejs.org → baixe LTS → instale com todas as opções marcadas → feche e reabra o terminal → teste:

Confirmar instalação
node -v && npm -v

🟡 Caso 3 — Erro com cap (Capacitor)

O setup do Passo 2 não terminou. Volte e rode o setup completo — ele instala o Capacitor localmente. Se já rodou, force a reinstalação:

Dentro da pasta do projeto
npm install
Dica geral: sempre que instalar Node, Java ou Android Studio, feche e reabra todos os terminais. Eles só enxergam o que foi instalado depois de reiniciar.
1

Extrair o ZIP

O ZIP que você baixou (ex: meuapp-v1.0.0-android.zip) está provavelmente na pasta Downloads.

Windows:

  1. Abra o Explorador de Arquivos (tecla Win + E).
  2. Cole este caminho na barra de endereço (no topo) e tecle Enter:
Caminho da pasta Downloads
C:\Users\SeuUsuario\Downloads
  1. Botão direito no arquivo meuapp-v1.0.0-android.zip → Extrair tudo... → Extrair.

Mac:

  1. Abra o Finder e vá em Downloads (no menu lateral).
  2. Duplo clique no arquivo meuapp-v1.0.0-android.zip — ele extrai sozinho.
→
Resultado esperado: uma pasta chamada meuapp-v1.0.0-android aparece em Downloads, contendo setup.bat, setup.sh, package.json.
NÃO abra esta pasta no Android Studio ainda. A pasta android/ não existe — ela é criada no passo 2.
2

Abrir o terminal NA pasta do projeto e rodar o setup

Você precisa do terminal apontando exatamente pra pasta extraída. Siga o método abaixo do seu sistema — é à prova de erro.

Windows — abrir o terminal na pasta certa:

  1. Abra o Explorador de Arquivos (Win + E).
  2. Cole este caminho na barra de endereço e tecle Enter:
Caminho do projeto
C:\Users\SeuUsuario\Downloads\meuapp-v1.0.0-android
  1. Você está dentro da pasta. Agora clique de novo na barra de endereço, apague tudo, digite cmd e tecle Enter (use cmd, não PowerShell — evita o erro "setup.bat não é reconhecido").
  2. Vai abrir uma janela preta já no caminho certo. Cole este comando e tecle Enter:
Rodar o setup (Windows)
.\setup.bat
Se abriu PowerShell por engano (fundo azul ou linha começando com PS C:\...): use exatamente 
.\setup.bat
com 
.\
na frente. Sem o 
.\
o PowerShell não acha o arquivo, mesmo estando na pasta certa — foi esse o erro "O termo 'setup.bat' não é reconhecido".

Mac — abrir o terminal na pasta certa:

  1. Abra o app Terminal (Cmd+Espaço, digite "terminal").
  2. Cole este comando e tecle Enter (entra na pasta):
Entrar na pasta do projeto
cd "/Users/seuusuario/Downloads/meuapp-v1.0.0-android"
  1. Cole este comando e tecle Enter (roda o setup):
Rodar o setup (Mac/Linux)
chmod +x setup.sh && ./setup.sh
Demora 5 a 10 minutos na primeira vez. Não feche o terminal. Vai aparecer muito texto rolando — é normal. Aguarde até ver "✅ Setup concluído" ou o cursor voltar a piscar livre.
→
Resultado esperado: dentro da pasta meuapp-v1.0.0-android agora existem as subpastas android/, node_modules/ e dist/. Não feche o terminal! Vai usar ele no passo 3.
3

Abrir o Android Studio (1 comando, vai na pasta certa sozinho)

No mesmo terminal do passo 2 (que já está dentro da pasta do projeto), cole este comando e tecle Enter:

Funciona em Windows e Mac
npm run cap:open:android
→
Resultado esperado: o Android Studio abre sozinho apontando direto pra pasta android/. Você vê na barra de cima o nome do projeto seguido de [app], e o botão verde ▶ aparece no canto superior direito.
Se fechou o terminal sem querer: abra outro seguindo de novo o passo 2 (parte "abrir o terminal na pasta certa") até a parte do cmd / cd. Aí rode o comando acima.
Erro "cap: command not found" ou "npm: comando não encontrado": o passo 2 não terminou. Volte e rode o setup de novo até o fim.
4

Esperar o Gradle Sync (apenas aguardar)

O Android Studio abriu. Não clique em nada. Olhe pra barra inferior:

  • Vai aparecer "Gradle Sync", depois "Indexing", depois "Downloading dependencies".
  • Pode demorar 5 a 15 minutos na primeira vez.

Se aparecer um banner amarelo no topo dizendo "Install missing platform" ou "Install build tools", clique no link azul Install e aguarde.

→
Resultado esperado: a barra inferior fica vazia/parada e no canto superior direito aparece o botão verde ▶ Run 'app'.
Se der erro "SDK location not found": File → Project Structure → SDK Location → escolha a pasta do SDK (C:\Users\SeuNome\AppData\Local\Android\Sdk no Windows).
5

(Opcional) Testar no celular antes de gerar o AAB

Pule este passo se quiser ir direto pro AAB. Mas testar antes evita perder tempo se houver problema.

  1. No celular: Configurações → Sobre o telefone → toque 7 vezes em "Número da versão".
  2. Volte → Opções do desenvolvedor → ative Depuração USB.
  3. Conecte o celular ao computador via cabo USB. Aceite o popup que aparecer no celular.
  4. No Android Studio, no topo, no dropdown ao lado do ▶, escolha o nome do seu celular.
  5. Clique no botão verde ▶ Run 'app'.
→
Resultado esperado: em cerca de 1 minuto o app abre no seu celular.
6

Criar a Keystore (SÓ na primeira vez na vida)

A keystore é a "assinatura digital" do seu app. Sem ela você não consegue subir na Play Store. Se perder, nunca mais consegue atualizar este app.

  1. No Android Studio: Build (menu superior) → Generate Signed App Bundle / APK...
  2. Selecione Android App Bundle → Next.
  3. Em Key store path, clique Create new...
  4. Em Key store path da nova janela, clique no ícone de pasta e salve em local SEGURO (ex: C:\Users\SeuNome\Documentos\minha-app.keystore). Não salve dentro da pasta do projeto.
  5. Preencha exatamente assim:
    • Password + Confirm: uma senha forte (anote em lugar seguro!)
    • Key alias: upload
    • Key password: pode usar a mesma do keystore
    • Validity (years): 25
    • First and Last Name: seu nome ou nome da empresa
    • Resto pode deixar vazio
  6. Clique OK.
FAÇA BACKUP AGORA. Copie o arquivo .keystore e anote a senha em: pendrive + Google Drive privado + gerenciador de senhas. Se perder, é game over para este app.
→
Resultado esperado: você volta automaticamente pra tela anterior, com o caminho do keystore preenchido.
7

Gerar o arquivo .aab (o que vai pra Play Store)

Continuando da tela do passo 6 (ou abra de novo: Build → Generate Signed App Bundle / APK):

  1. Confirme que o caminho do keystore está preenchido, digite a senha e o alias upload.
  2. Marque Remember passwords se quiser (opcional).
  3. Clique Next.
  4. Em Build Variants, selecione release (clique nele pra ficar marcado em azul).
  5. Clique Create.

Vai compilar por 2 a 5 minutos. Aguarde a notificação no canto inferior direito: "App bundle(s) generated successfully".

Clique no link locate dessa notificação. Vai abrir a pasta com o arquivo final:

android/app/release/app-release.aab
→
Resultado esperado: o arquivo app-release.aab existe e tem tamanho entre 5 MB e 30 MB.
8

Subir o .aab na Play Console

  1. Acesse play.google.com/console e faça login.
  2. Selecione seu app (ou crie um novo se for a primeira vez).
  3. Menu lateral: Produção → Criar nova versão.
  4. Em App bundles, clique Fazer upload e selecione o app-release.aab.
  5. Preencha as notas da versão e clique Próximo → Iniciar lançamento na produção.
→
Resultado esperado: app em análise pelo Google (geralmente liberado em 1 a 24h).
9

Atualizações futuras (versão 2, 3, ...)

Quando precisar atualizar o app na Play Store:

  1. Volte aqui no painel, abra seu app salvo, e incremente a versão (ex: 1.0.0 → 1.0.1 e versionCode 1 → 2).
  2. Baixe o ZIP novo.
  3. Repita os passos 1, 2, 3, 4 e 7. Pule o passo 6 — use a MESMA keystore que você criou da primeira vez.
  4. No passo 7, na tela de seleção de keystore, aponte para o arquivo .keystore que você guardou.
  5. Suba o novo .aab na Play Console.
Usar uma keystore diferente da original = Google rejeita a atualização. Sempre a mesma!

Coletar e salvar os logs do setup

Em vez de copiar pedaço por pedaço do terminal, rode o setup pelo wrapper de log: ele grava tudo (stdout + stderr + versões de Node/npm/Java) num único arquivo setup-log.txt dentro da pasta do projeto. Aí é só anexar pra eu (ou qualquer pessoa) diagnosticar rápido.

Windows — no terminal já dentro da pasta do projeto:

No CMD
setup-with-log.bat
No PowerShell
.\setup-with-log.bat

Mac / Linux — no Terminal já dentro da pasta do projeto:

Mac/Linux
chmod +x setup-with-log.sh && ./setup-with-log.sh
Quando terminar (com sucesso ou erro), o arquivo setup-log.txt aparece dentro da pasta do projeto, no mesmo lugar do setup.bat. Abra o Explorador/Finder, arraste o arquivo pra mensagem de chat e pronto.

Bônus: baixe um arquivo de diagnóstico com seus dados (caminho do projeto, navegador, instruções) já preenchidos — mande junto com o setup-log.txt.

Wrapper não existe na pasta? Os arquivos setup-with-log.bat / setup-with-log.sh só aparecem em ZIPs gerados depois desta atualização. Se o seu ZIP for antigo, gere o app de novo no painel ou rode o setup normal redirecionando manualmente: setup.bat > setup-log.txt 2>&1 (Windows) ou ./setup.sh > setup-log.txt 2>&1 (Mac).

Diagnóstico inteligente de erro

Cole a mensagem de erro do Gradle / Android Studio e a IA devolve a causa provável e o comando exato pra rodar.

0/12000

🆘 Erros comuns

  • "JAVA_HOME not set" → o JDK do Android Studio fica em C:\Program Files\Android\Android Studio\jbr (Win) ou Android Studio.app/Contents/jbr (Mac). Configure como variável de ambiente.
  • "Execution failed for task ':app:processReleaseResources'" → ícone faltando. Volte na pasta do projeto e rode npm run apply:icons.
  • Tela branca no app → sua URL precisa ser HTTPS público (não localhost, não HTTP).
  • "Duplicate class" ou "Manifest merger failed" → menu Build → Clean Project, depois Rebuild Project.
  • Gradle travado → feche o Android Studio. No terminal: cd android && ./gradlew --stop && ./gradlew clean. Abra de novo.
Travou em algum passo? Cole o erro no diagnóstico inteligente acima ou me mande print. 💬