Referência de comandos e conceitos Flutter/Dart

Propósito. Informa as versões do framework Flutter, engine, Dart SDK e ferramentas relacionadas.

Quando usar. No início do projeto, em relatórios de falha e antes de comparar resultados entre máquinas ou CI.

O que registrar. Canal utilizado, versão do Flutter e versão do Dart. Uma aplicação reproduzível precisa declarar sua toolchain, não apenas suas dependências.

Propósito. Examina a instalação e verifica se as toolchains necessárias para os alvos conhecidos estão disponíveis. Ele pode avaliar o SDK Flutter, Android SDK, Xcode no macOS, navegadores, IDEs e dispositivos.

Como interpretar. ✓ indica que a verificação passou; ! representa atenção ou configuração incompleta; ✗ aponta uma falha. Um alerta de iOS não bloqueia um curso executado apenas para Android e web.

Variação útil. flutter doctor -v mostra caminhos, versões e detalhes que ajudam a encontrar SDK duplicado ou variável de ambiente incorreta.

O que ele não faz. Não instala nem corrige automaticamente todas as dependências. O diagnóstico precisa ser lido de acordo com a plataforma que você pretende entregar.

Prática recomendada. Execute a versão detalhada, escolha cada item diferente de ✓ e classifique-o como bloqueador do seu alvo, melhoria opcional ou irrelevante para o momento.

Propósito. Exibe ou altera configurações persistentes do Flutter CLI, como habilitação de plataformas e caminhos suportados pela versão instalada.

Cuidado. Uma configuração global afeta outros projetos daquela máquina. Antes de mudar algo, execute flutter config sem argumentos e registre o estado anterior.

Propósito. Lista os alvos conectados que o Flutter consegue utilizar, com nome, identificador e plataforma.

Uso comum. Copie o identificador e execute flutter run -d <deviceId>. Se o dispositivo não aparecer, confirme conexão, autorização, drivers, depuração USB ou disponibilidade do navegador.

Propósito. Lista emuladores configurados e permite iniciar um deles com flutter emulators --launch <emulatorId>.

Diferença importante. Emulador é o ambiente virtual cadastrado; device é um alvo já disponível para execução. Depois de iniciar o emulador, confirme sua presença com flutter devices.

Propósito. Gera a estrutura de um aplicativo Flutter e, por padrão, resolve suas dependências.

O que observar. pubspec.yaml, lib/main.dart, test/ e as pastas de plataforma. O código compartilhado não elimina os pontos de integração nativa.

Decisão. Consulte flutter create --help antes de escolher plataformas, identificador de organização ou template. Alterar identificadores de pacote depois pode afetar assinatura, Firebase e publicação.

Saída esperada. O diretório é criado, as dependências são resolvidas e o CLI apresenta os próximos comandos. Leia a saída em vez de tratá-la como ruído.

Propósito. Compila e executa o aplicativo em um dispositivo, mantendo uma sessão de desenvolvimento conectada.

Modo padrão. Em geral, executa em debug, com asserts, VM service e Hot Reload. Esse modo favorece diagnóstico, não representa desempenho ou tamanho de produção.

Durante a sessão. r solicita Hot Reload; R solicita Hot Restart; q encerra. Hot Reload injeta código atualizado e reconstrói a árvore, mas pode não reaplicar inicializadores ou mudanças nativas.

Falha frequente. Mais de um dispositivo disponível sem seleção explícita. Use flutter devices e informe -d para tornar o resultado previsível.

Propósito. Conecta as ferramentas Flutter a uma engine que já está executando. É útil em cenários add-to-app ou quando a aplicação foi iniciada pelo host nativo.

Não confunda. run inicia e acompanha a aplicação; attach encontra uma execução existente.

Propósito. Resolve as restrições do pubspec.yaml, baixa pacotes ausentes e materializa a resolução no lockfile quando aplicável.

Quando executar. Depois de alterar dependências ou obter uma revisão cujo lockfile mudou. Para aplicativo Flutter, prefira flutter pub a dart pub, pois o Flutter CLI considera o SDK Flutter durante a resolução.

Não confunda. get respeita a resolução possível e o lockfile; upgrade busca versões mais novas permitidas pelas restrições e pode alterar o lockfile.

Propósito. Adiciona uma dependência ao pubspec.yaml e resolve os pacotes.

Antes de adicionar. Verifique manutenção, plataformas suportadas, licença, histórico de segurança, API e custo de integração. Popularidade não substitui avaliação técnica.

Propósito. Compara versões atuais, atualizáveis, resolvíveis e mais recentes. Ele ajuda a separar “há versão nova” de “o conjunto atual de restrições aceita essa versão”.

Uso responsável. Atualize em pequenos grupos, leia changelogs e execute análise, testes e smoke test. Dependência atualizada não significa aplicação validada.

Propósito. Gera as classes de localização a partir da configuração e dos arquivos ARB do projeto.

Falha frequente. Chave ausente, placeholder incompatível entre idiomas ou configuração divergente. Arquivos gerados não devem ser corrigidos manualmente; corrija a fonte e gere novamente.

Propósito. Executa análise estática usando o analisador Dart e as regras de analysis_options.yaml. Detecta erros de tipo, usos inválidos, avisos e lints sem executar a aplicação.

Como interpretar. Leia arquivo, linha, severidade, código do diagnóstico e mensagem. Corrija a causa; não silencie uma regra apenas para deixar o pipeline verde.

Limite. Análise estática não prova comportamento, integração ou experiência. Ela complementa testes e revisão.

Propósito. Executa testes Dart e Flutter do pacote. Pode receber arquivo, diretório, nome e opções de plataforma.

Variações. flutter test --coverage produz dados de cobertura; flutter test test/products/ reduz o escopo durante o desenvolvimento.

Saída esperada. Contagem de testes e resultado final. Um teste intermitente continua sendo falha: repeti-lo até ficar verde não corrige a causa.

Propósito. Acompanha logs de aplicações Flutter em dispositivos conectados.

Cuidado. Logs podem conter dados pessoais, tokens e payloads. A política de redação deve existir no código; apagar o terminal depois não remove exposição de observabilidade remota.

Propósito. Produz um artefato para um alvo, como appbundle, apk, ipa, web, windows, macos ou linux, quando suportado pelo host e pelo projeto.

Release não é publicação. O comando gera artefatos; assinatura, distribuição, revisão de loja, rollout e observação pós-release são etapas distintas.

Antes do build. Confirme ambiente, configuração, versão, assinatura, segredos, análise e testes. Registre o caminho e o hash do artefato produzido.

Propósito. Instala um aplicativo Flutter em um dispositivo conectado. É útil para validar um artefato ou uma execução mais próxima da distribuição.

Limite. Instalação bem-sucedida não prova inicialização, migração, login ou fluxos críticos; execute um smoke test depois.

Propósito. Remove saídas de build e arquivos gerados pelo sistema de compilação para forçar reconstrução.

Quando usar. Quando há evidência de cache ou artefato intermediário inconsistente, especialmente após mudanças profundas de toolchain ou configuração nativa.

Quando evitar. Não transforme clean na primeira resposta a qualquer erro. Ele aumenta o tempo do próximo build e pode apenas esconder um problema não compreendido.

Propósito. Atualiza o SDK Flutter no canal atual.

Cuidado. Toolchain é dependência do projeto. Faça a atualização em mudança controlada, leia notas, registre versões e execute a validação completa. Não atualize silenciosamente no meio de um diagnóstico.

Executa um programa Dart, um script do projeto ou um executável fornecido por dependência. Argumentos depois do alvo são entregues à função main(List<String> args).

Use --enable-asserts quando precisar habilitar asserts em um contexto que não os ativa por padrão. Para observar um programa de linha de comando com DevTools, consulte dart run --observe.

Formata os arquivos segundo o formatador oficial. Formatação reduz discussões de estilo; não altera a responsabilidade de revisar o código.

No CI, dart format --output=none --set-exit-if-changed . verifica sem reescrever e retorna falha quando encontra divergência.

Analisa um pacote Dart sem dependências de interface Flutter. É especialmente útil nos pacotes de domínio e ferramentas do curso.

dart analyze e flutter analyze compartilham o analisador, mas o comando Flutter prepara o contexto de uma aplicação Flutter.

Mostra correções automatizadas disponíveis para diagnósticos e migrações conhecidas. Revise a proposta antes de executar dart fix --apply.

Correção automática não conhece a intenção do negócio. Analise o diff e execute testes depois da aplicação.

Executa testes de um pacote Dart. Use-o para validar domínio, utilitários e código que não precisa carregar Flutter.

Prefira testes pequenos e determinísticos. Rede, relógio e aleatoriedade devem ser controlados por dependências substituíveis.

Gera documentação de API a partir das bibliotecas públicas e comentários de documentação. Avisos revelam referências quebradas ou APIs mal documentadas.

Documentar tudo não é o objetivo; documente contratos, decisões, limites e comportamentos que não são evidentes pelo nome.

Compila programas Dart para formatos suportados, como executável nativo, snapshot AOT, kernel ou JavaScript, conforme plataforma e versão.

Escolha o formato pelo ambiente de execução. Um artefato AOT favorece inicialização e distribuição; execução JIT favorece desenvolvimento e diagnóstico.