Variáveis de Ambiente: o que são, uso e configuração em projetos mobile

O que são Variáveis de Ambiente

Variáveis de ambiente são pares chave-valor acessíveis ao processo da aplicação através da API do sistema operacional. Elas são passadas ao processo quando ele é criado e existem apenas durante sua execução. Ao contrário dos parâmetros de configuração embutidos no código fonte, as variáveis de ambiente não exigem recompilação para alterar valores. Este é um princípio fundamental do Twelve-Factor App, que garante uma separação clara entre código e configuração.

No desenvolvimento mobile, as variáveis de ambiente resolvem o problema de diferentes configurações para ambientes: o desenvolvedor usa um servidor local, o testador usa staging e os usuários usam produção. Em vez de armazenar três URLs de backend no código com instruções condicionais if-else, o desenvolvedor passa uma URL através de uma variável de ambiente em tempo de compilação. Isso simplifica o código e elimina o risco de usar acidentalmente o servidor de produção em um ambiente de teste.

A principal vantagem é a segurança: dados sensíveis não vão parar no repositório de código. Chaves de API, segredos do Firebase, tokens de acesso ao backend e certificados são carregados via CI/CD diretamente no ambiente de compilação. Se um invasor obtiver acesso ao repositório de código, não encontrará segredos lá, pois eles são armazenados em armazenamentos protegidos do sistema CI e são passados apenas na etapa de compilação do arquivo binário.

Por que as Variáveis de Ambiente são necessárias no desenvolvimento mobile

Projetos mobile têm pelo menos três ambientes: desenvolvimento, staging e produção. Cada ambiente requer seu próprio conjunto de configurações: URL do servidor, nome do pacote, esquema de assinatura e certificados de notificações push. Sem variáveis de ambiente, o desenvolvedor precisa alterar manualmente a configuração antes de cada compilação, o que leva a erros: uma chave de produção esquecida em uma compilação de teste pode causar o envio de notificações para usuários reais ou consumo de API paga.

Separação de Ambientes

Variáveis de ambiente permitem alternar o backend sem alterar o código: basta alterar o valor na variável API_BASE_URL. Flags de funcionalidade são gerenciadas através de variáveis como FEATURE_CHAT_ENABLED=true, permitindo ativar novos recursos em staging sem afetar a produção. Cada ambiente tem seu próprio arquivo .env que é carregado em tempo de compilação.

class AppConfig {
  static final String apiBaseUrl =
    const String.fromEnvironment('API_BASE_URL',
      defaultValue: 'http://localhost:8080');
}

Segurança de Chaves

Chaves codificadas são uma vulnerabilidade comum em aplicações mobile. Um invasor descompila o APK ou IPA usando ferramentas como jadx ou Hopper e extrai segredos do arquivo binário. Mesmo a ofuscação não protege literais de string — eles são facilmente encontrados no código após a descompilação. Variáveis de ambiente resolvem esse problema passando chaves em tempo de compilação via CI/CD, onde elas são mascaradas nos logs.

object Config {
    val apiKey: String =
        System.getenv("API_KEY") ?: throw
            IllegalStateException("API_KEY not set")
}

Integração CI/CD

Variáveis de ambiente se integram com pipelines de compilação: GitHub Actions, GitLab CI, Bitrise e CircleCI suportam variáveis secretas que não são exibidas nos logs. Em tempo de compilação, o CI substitui os valores apropriados dependendo do branch ou tag: para o branch develop usa staging, para a tag v* usa produção. Isso automatiza o processo e elimina o fator humano, garantindo que cada compilação receba o conjunto correto de configuração.

Arquivos .env e bibliotecas de gerenciamento

O arquivo .env é uma forma padrão de armazenar variáveis de ambiente no formato KEY=VALUE. Ele não é incluído no repositório; em vez disso, .env.example é adicionado com um modelo de todas as variáveis e valores vazios. Cada desenvolvedor cria seu próprio arquivo .env com configurações locais sem afetar as configurações dos outros membros da equipe. Arquivos separados são usados para diferentes ambientes: .env.dev, .env.stage, .env.prod.

# .env.example — template para desenvolvedores
API_BASE_URL=http://localhost:8080
FEATURE_CHAT_ENABLED=true
SENTRY_DSN=

Para projetos mobile, existem bibliotecas especializadas para trabalhar com arquivos .env:

• flutter_dotenv (Flutter) — carrega variáveis do .env em tempo de execução via dotenv.load()
• BuildConfig (Android) — gera campos tipados a partir de valores do build.gradle
• xcconfig (iOS) — conecta arquivos de configuração a diferentes esquemas de compilação do Xcode
• react-native-config (React Native) — gerenciamento de variáveis através de arquivos .env

As configurações de ramificação em CI/CD permitem substituir diferentes arquivos .env: .env.dev para servidores de teste, .env.stage para pré-lançamento e .env.prod para publicação em lojas de aplicativos. Arquivos com segredos são carregados de um armazenamento seguro (Vault, AWS Secrets Manager) e não são armazenados no repositório. Isso garante que mesmo se o sistema de controle de versão for comprometido, os segredos permanecem protegidos.

Variáveis de Ambiente em projetos iOS

O ecossistema iOS usa arquivos xcconfig para gerenciar variáveis no nível de compilação. Eles são anexados a esquemas do Xcode e permitem sobrescrever valores para configurações Debug e Release. Arquivos xcconfig suportam herança: você pode criar um arquivo base com configurações comuns e arquivos específicos para cada ambiente.

Configuração de arquivos xcconfig

Arquivos xcconfig armazenam variáveis no formato KEY = VALUE e são anexados a um esquema de compilação no Xcode através das configurações de Configuration. Variáveis do xcconfig estão disponíveis no Info.plist através da sintaxe $(NOME_VARIAVEL), permitindo diferentes identificadores de pacote e nomes de aplicativo para diferentes esquemas. Para identificação rápida do ambiente, o sufixo Dev ou Staging é adicionado ao nome do aplicativo.

# Config/Dev.xcconfig — configuração de desenvolvimento
API_BASE_URL = http://localhost:3000
BUNDLE_ID_SUFFIX = .dev
APP_DISPLAY_NAME = MyApp Dev

Código Swift para ler variáveis

Para acesso em tempo de execução a variáveis no iOS, o arquivo Configuration.swift é usado, que lê valores do Info.plist através de Bundle.main.object(forInfoDictionaryKey:). Esta abordagem garante que as variáveis são definidas em tempo de compilação e estão disponíveis para a aplicação imediatamente após a inicialização. Os valores são lidos uma vez durante a inicialização do módulo e armazenados em cache para acesso rápido durante todo o ciclo de vida da aplicação.

enum AppEnvironment {
    static var apiBaseURL: URL {
        guard let urlString = Bundle.main
            .object(forInfoDictionaryKey: "API_BASE_URL"),
              let url = URL(string: urlString as! String)
        else { fatalError("API_BASE_URL is not configured") }
        return url
    }

    static var isChatEnabled: Bool {
        Bundle.main.object(
            forInfoDictionaryKey: "FEATURE_CHAT_ENABLED"
        ) as? Bool ?? false
    }
}

Variáveis de Ambiente em projetos Android

O Android suporta variáveis de ambiente através do BuildConfig — uma classe gerada automaticamente cujos campos são definidos no arquivo build.gradle do módulo. O BuildConfig é criado em tempo de compilação para cada flavor e tipo de compilação separadamente. Isso permite ter valores diferentes para debug e release sem usar operadores condicionais no código, melhorando o desempenho e a segurança.

Configuração de campos BuildConfig

Os campos do BuildConfig são definidos através de buildConfigField no defaultConfig ou em buildTypes específicos. Um buildType ou productFlavor separado é criado para cada ambiente. Isso garante um isolamento estrito de configuração: debug usa um servidor local, release usa produção. Os campos BuildConfig são estaticamente tipados, o que elimina erros ao acessá-los no código.

// build.gradle (Module: app)
android {
    defaultConfig {
        buildConfigField "String", "API_BASE_URL",
            "\"http://localhost:8080\""
    }
    buildTypes {
        debug {
            buildConfigField "String", "API_BASE_URL",
                "\"http://dev.api.itsectr.com\""
        }
        release {
            buildConfigField "String", "API_BASE_URL",
                "\"https://api.itsectr.com\""
        }
    }
}

gradle.properties para valores compartilhados

O arquivo gradle.properties na raiz do projeto armazena variáveis globais do Gradle. Elas estão disponíveis em todos os módulos através da sintaxe $variableName e são usadas para especificar versões de dependências, flags de compilação e chaves de API. Ao contrário do BuildConfig, o gradle.properties funciona apenas na etapa de configuração do Gradle, não em tempo de execução da aplicação. Portanto, senhas e chaves de API especificadas no gradle.properties não são visíveis no código descompilado, pois são usadas apenas para gerar o BuildConfig em tempo de compilação.

# gradle.properties
SENTRY_DSN=https://key@sentry.io/project
MAPS_API_KEY=AIzaSy...

Para transferência segura de segredos em projetos Android, recomenda-se usar local.properties (excluído do VCS) ou carregar valores de variáveis CI/CD no build.gradle através de System.getenv(). Isso garante que as chaves não vão parar no repositório. Ao publicar no Google Play Console, certifique-se de que todas as chaves de depuração sejam substituídas por versões de produção através de diferentes buildTypes ou productFlavors com valores correspondentes do BuildConfig.