Passos para Diagnóstico em Dispositivo Real

1. Conecte o dispositiov ao computador e ative a Depuração USB.
2. Abra o navegador Chrome e acesse chrome://inspect/#devices (ou edge://inspect/#devices no Edge) para visualizar o console e detectar erros.
3. Use a ferramenta de busca (atalho Ctrl+F) na aba Console para localizar o nome do método ou mensagem de erro e identificar o trecho exato do probleam.
4. Se o erro vier de um plugin, abra o Android Studio, localize o arquivo Java correspondente e execute o projeto em modo debug. Insira breakpoints e pressione F9 para avançar. Você pode alterar o código Java diretamente, testar a correção e depois aplicar a mesma mudança no fonte do plugin.

Exemplo Real: Erro de Permissão em Plugin File

Ao encontrar o erro FileError {code: 2, message: 'SECURITY_ERR'}, a inevstigação mostrou que o problema era do plugin File no Android 6+ (API 23). A partir desta versão, permissões precisam ser solicitadas dinamicamente, mas o plugin assumia que todas as permissões já estavam concedidas. A solução foi adicionar código para verificar e solicitar a permissão em tempo de execução. Para encontrar a correção, acesse o repositório do plugin no GitHub, compare as tags de versão e veja a partir de qual release o código de permissão dinâmica foi introduzido.

Advertência sobre Celulares OPPO

Dispositivos OPPO podem bloquear a instalação de aplicativos não registrados (não submetidos à loja oficial). Isso impede que o app seja aberto após a instalação via cabo USB. Fique atento a esse comportamento.

Erro npm: Cannot read properties of undefined (reading ‘extraneous’)

Esse erro geralmente é causado por resíduos de compilações anteriores no arquivo package-lock.json. Para resolver, remova a pasta node_modules e o arquivo package-lock.json, depois execute npm i novamente.

Problema de Versão do JDK e Compilação

Em cenário com múltiplos JDKs controlados por variável de ambiente, pode ocorrer discrepância entre o Java exibido no terminal (1.8) e o usado pela ferramenta de build (ex.: JDK 17). Exemplo de erro:

Requirements check failed for JDK 1.8.x! Detected version: 17.0.10
Check your ANDROID_SDK_ROOT / JAVA_HOME / PATH environment variables.

Solução encontrada: compilar pelo Android Studio (que baixou a versão correta do NDK) e, a partir do VS Code, executar ionic cordova prepare android para sincronizar as alterações do TypeScript, antes de buildar novamente no Android Studio.

Limpar Cache do JDK (Windows/Mac)

1. Acesse o Painel de Controle (Windows) ou Preferências do Sistema (Mac).
2. Abra o Java Control Panel.
3. Na aba Geral, clique em Configurações... na seção "Arquivos Temporários da Internet".
4. Clique em Excluir Arquivos e confirme.
5. Feche o painel.

Verificação do build.gradle

No Android Studio, confira se o arquivo build.gradle (nível módulo) contém as configurações de compatibilidade Java:

tasks.withType(JavaCompile) {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

Equivalência de Comandos Ionic Cordova

ionic cordova build android realiza as mesmas etapas de ionic cordova prepare android seguido de ionic cordova compile android.