Firebase Cloud Functions — o que é, gatilhos e como escrever funções

O que são Firebase Cloud Functions e como funcionam

Firebase Cloud Functions é uma plataforma de computação construída sobre o Google Cloud Functions (GCF), adaptada para o ecossistema Firebase. As funções são código JavaScript ou TypeScript comum exportado de um módulo e registrado para um tipo específico de evento. Quando um evento ocorre (por exemplo, um usuário se registra ou envia um arquivo), o Firebase Cloud Functions executa o código correspondente, passando o contexto do evento.

A arquitetura do Cloud Functions segue o princípio da responsabilidade única: uma função lida com um tipo de evento e executa uma operação atômica. Por exemplo, a função sendWelcomeEmail é acionada quando um novo usuário é criado no Firebase Authentication e envia um e-mail de boas-vindas. Esse isolamento simplifica a depuração, os testes e a reutilização de funções em diferentes projetos.

Cada função é executada em um contêiner isolado com um ciclo de vida temporário. O tempo máximo de execução padrão é de 60 segundos (funções HTTPS — 9 minutos). Se uma função não for concluída dentro do tempo limite, a requisição falha com erro 500. Para operações de longa duração, use Cloud Tasks ou Pub/Sub com repetições. Os contêineres podem ser reutilizados para chamadas subsequentes (keep-alive), reduzindo a latência em inicializações a frio após a primeira chamada.

Ambiente de execução e versões do Node.js

Firebase Cloud Functions suporta várias versões do Node.js: 18, 20 e 22 (recomendada para novos projetos). A versão é especificada no campo engines do arquivo package.json. O Firebase CLI configura automaticamente o ambiente de execução com base na versão especificada. Importante: o Firebase Cloud Functions não suporta a execução de contêineres Docker arbitrários — o ambiente é estritamente fixado pelo Google Cloud Functions.

Para novos projetos, recomenda-se Node.js 22, pois inclui as últimas otimizações do V8, suporte aprimorado a módulos ESM e suporte a WebSocket em nível de plataforma. Se um projeto usar dependências compiladas para uma versão específica do Node (por exemplo, módulos nativos C++), a compatibilidade deve ser verificada individualmente — nem todos os módulos nativos compilam no ambiente GCF.

Diferença entre Firebase Cloud Functions e Google Cloud Functions

Firebase Cloud Functions é um invólucro sobre o Google Cloud Functions com Firebase SDK pré-instalado e integração com os serviços do Firebase. O desenvolvedor escreve código usando o SDK firebase-functions, que fornece gatilhos tipados para todos os serviços do Firebase. O Google Cloud Functions é uma plataforma de nível inferior onde os gatilhos são configurados explicitamente através do Eventarc ou Pub/Sub.

A principal diferença: no Firebase Cloud Functions, um gatilho é registrado declarativamente através de functions.firestore.document('path').onWrite(), enquanto no Google Cloud Functions é configurado através do Eventarc com filtragem de atributos de evento. O Firebase Cloud Functions também vem com o Admin SDK inicializado automaticamente com as credenciais da conta de serviço do projeto, fornecendo acesso completo a todos os serviços do Firebase sem configuração adicional.

Tipos de gatilhos: quais eventos são suportados

Firebase Cloud Functions suporta 8 categorias de gatilhos, cada uma correspondendo a um serviço específico do Firebase ou Google Cloud. Um gatilho é uma condição que, quando atendida, invoca automaticamente uma função. O desenvolvedor não gerencia o ciclo de vida da função diretamente: o Firebase CLI registra o gatilho no Google Cloud Eventarc, e a plataforma em nuvem executa a função quando o evento ocorre.

Os gatilhos mais populares são os gatilhos do Firestore: onWrite, onCreate, onUpdate, onDelete. Eles são acionados quando documentos nas coleções do Firestore são alterados. A função recebe instantâneos do documento antes e depois da alteração, permitindo comparar valores e reagir apenas a mudanças específicas. Por exemplo, quando o status de um pedido muda de “pendente” para “enviado”, uma notificação push pode ser enviada ao usuário.

Os gatilhos de Authentication (onCreate, onDelete) são acionados quando uma conta de usuário é criada ou excluída. Eles são usados para inicializar dados do usuário: criar um documento de usuário no Firestore, enviar um e-mail de boas-vindas, escrever em analytics. Nota: a função não pode cancelar a criação do usuário — ela é executada após a conta já ter sido criada. Para pré-validação, use as Blocking Functions disponíveis na Identity Platform.

Gatilhos HTTPS e CORS

As funções HTTPS (onRequest) permitem criar endpoints de API REST completos acessíveis via HTTP. Ao contrário dos gatilhos baseados em eventos, as funções HTTPS são invocadas através de uma URL no formato https://{region}-{project}.cloudfunctions.net/{functionName}. É importante configurar o CORS corretamente se o endpoint for chamado de um navegador ou aplicativo móvel. O Firebase SDK não inclui cabeçalhos CORS automaticamente — eles devem ser adicionados manualmente via middleware.

Para clientes móveis (Android, iOS), o CORS não é necessário, pois os clientes HTTP nativos não são restritos pela política de Cross-Origin. O CORS é relevante apenas para requisições web. Se sua função HTTPS for chamada tanto do aplicativo quanto da web, adicione um tratamento CORS universal: res.set('Access-Control-Allow-Origin', '*') para desenvolvimento ou uma lista de domínios permitidos para produção.

Agendamento com Pub/Sub e Cloud Scheduler

Para execução periódica (tarefas cron), use uma combinação de Cloud Scheduler e Pub/Sub. O Cloud Scheduler envia uma mensagem para um tópico do Pub/Sub em um cronograma, e o gatilho onPublish do Cloud Functions processa essa mensagem. O Firebase CLI não suporta sintaxe cron direta — o cronograma é configurado através do console do Google Cloud ou Terraform no formato unix-cron: 0 3 * * * (todos os dias às 3:00).

Exemplos de tarefas: boletim diário, limpeza de dados obsoletos, geração de relatórios, sincronização com APIs externas. Importante: o Cloud Scheduler é um serviço pago do Google Cloud (cerca de $2 por mês por trabalho). Cada acionamento conta como uma chamada de função separada e é faturado pelas taxas padrão do Cloud Functions.

Como escrever e implantar funções

O desenvolvimento de Cloud Functions começa inicializando um projeto via Firebase CLI: firebase init functions. Este comando cria um diretório functions/ com um modelo index.js (ou index.ts), um arquivo package.json e configuração TypeScript (se selecionado). Após a inicialização, basta escrever uma função, exportá-la do módulo e executar firebase deploy --only functions para implantar.

Cada função é registrada chamando o método de gatilho apropriado. Exemplo de uma função HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send(“Hello!”); }). O Firebase Functions usa um modelo assíncrono: para gatilhos baseados em eventos (não HTTPS), a função deve retornar uma Promise. O Firebase aguarda a conclusão da Promise antes de encerrar o contêiner. Se uma Promise não for retornada, a função pode ser encerrada antes que as operações assíncronas terminem.

O desenvolvimento local é feito através do Firebase Emulator Suite, que inclui um emulador do Cloud Functions. O comando firebase emulators:start inicia um servidor local com funções acessíveis em http://localhost:5001. O emulador suporta recarga a quente quando o código é alterado e é totalmente isolado do ambiente de produção, permitindo testes sem risco para dados reais.

Gerenciamento de dependências e configuração

As dependências do Cloud Functions são gerenciadas através do package.json. O Firebase instala apenas dependências de produção (dependencies, não devDependencies). O tamanho do pacote de funções afeta o tempo de inicialização a frio: recomenda-se minimizar o número de dependências. A dependência firebase-admin está pré-instalada para o Firebase Admin SDK — não é necessário adicioná-la manualmente.

Os dados confidenciais (chaves de API, tokens) não devem ser armazenados no código da função. Use functions.config() para armazenar configuração: firebase functions:config:set stripe.key=“sk_...”. Os valores são criptografados e estão disponíveis em tempo de execução via functions.config().stripe.key. Para configurações serializadas grandes, use o Google Cloud Secret Manager.

Tratamento de erros e registro

O registro no Cloud Functions é feito através de console.log, console.warn e console.error. Todos os logs são coletados automaticamente no Google Cloud Logging e estão disponíveis no console do Firebase (Functions > Logs). Para registro estruturado, use as bibliotecas winston ou pino, que suportam formatação JSON e níveis de log.

O tratamento de erros é crítico para a confiabilidade: uma exceção não tratada em uma Promise encerra a função com erro, após o que o Firebase tenta automaticamente novamente com backoff exponencial. O número de repetições é configurável: de 0 a infinito. Para gatilhos baseados em eventos, recomenda-se ativar as repetições para garantir que cada evento seja processado mesmo durante falhas temporárias de serviços externos.

Inicialização a frio e escalabilidade

A inicialização a frio (cold start) é o atraso na primeira invocação de uma função após um período de inatividade, quando o contêiner com o código é carregado e inicializado novamente. De acordo com a documentação do Firebase (2026), uma inicialização a frio leva de 200 ms a 2 segundos, dependendo do tamanho do pacote, número de dependências e região. Para a interface do usuário, um atraso superior a 1 segundo é perceptível e pode afetar a experiência do usuário.

Formas de minimizar a inicialização a frio: minimizar dependências, usar TypeScript compilado para CommonJS, reduzir o tamanho do pacote de funções, definir um número mínimo de instâncias ativas. O Firebase Cloud Functions v2 (2ª geração) permite definir minInstances — o número mínimo de contêineres aquecidos sempre prontos para processar requisições. Manter contêineres aquecidos gera custos por tempo ocioso.

A escalabilidade do Cloud Functions ocorre automaticamente: à medida que o volume de requisições aumenta, o Firebase cria novos contêineres. Por padrão, o número máximo de instâncias paralelas é 3000 (cota do projeto Google Cloud). Cada instância lida com uma requisição por vez. Se uma função for rápida (menos de 100 ms), uma instância pode lidar com até 10 requisições por segundo, fornecendo uma taxa de transferência de pico de até 30.000 requisições por segundo por projeto.

Configurando minInstances e maxInstances

minInstances é um parâmetro que reserva um número específico de contêineres e os mantém aquecidos. É recomendado para funções HTTPS críticas onde a latência de inicialização a frio é inaceitável. Por exemplo, para um endpoint de autenticação, defina minInstances: 1. maxInstances limita o número máximo de instâncias paralelas, útil para evitar crescimento descontrolado de custos durante picos repentinos de tráfego.

A configuração é feita no código: functions.runWith({ minInstances: 1, maxInstances: 10 }). Importante: minInstances aumenta o custo porque os contêineres funcionam continuamente. Para projetos de teste, minInstances deve ser desativado. Para produção, minInstances é recomendado para todas as funções HTTPS públicas e 0 para gatilhos baseados em eventos onde um atraso de 1 segundo não é crítico.

Regiões de implantação

A região de implantação afeta a latência para os usuários finais e o custo do tráfego de saída. O Firebase Cloud Functions está disponível em mais de 30 regiões do Google Cloud. Para aplicativos móveis, escolha a região mais próxima do seu público-alvo: us-central1 para as Américas, europe-west1 para a Europa, asia-east2 para a Ásia. A região não pode ser alterada após a implantação sem reimplantar a função.

A alteração da região é feita através do parâmetro region no código: functions.region('europe-west1'). Todas as funções em um único arquivo podem ter regiões diferentes. Para projetos globais, recomenda-se implantar funções em várias regiões e usar o Cloud Load Balancing para distribuir o tráfego, embora para a maioria dos aplicativos móveis uma única região seja suficiente se escolhida corretamente.

Exemplos de código para Firebase Cloud Functions

Vamos ver exemplos práticos de Cloud Functions em TypeScript. O código usa o Firebase Functions SDK v2 (2ª geração) com sintaxe de módulos ES. Os exemplos incluem o tratamento de um evento de criação de usuário, a geração de uma miniatura no upload de imagem e um endpoint HTTPS simples para uma API REST. Todas as funções são assíncronas e retornam uma Promise para o encerramento correto do contêiner.

Antes de executar, certifique-se de que o Firebase CLI está atualizado para a versão 13+: npm install -g firebase-tools. As funções v2 exigem o plano de preços Blaze. Inicialização: firebase init functions com TypeScript selecionado.

Tratamento de registro de usuário

O primeiro exemplo — criação de um documento no Firestore quando um novo usuário se registra. A função é acionada pelo evento auth.user().onCreate e escreve um perfil básico na coleção users/{uid}. Isso garante que cada usuário registrado tenha um documento com os campos necessários.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

A função createUserProfile é assíncrona — ela retorna uma Promise que o Firebase aguarda antes de encerrar. Se a gravação no Firestore falhar (por exemplo, devido a permissões insuficientes), a função será repetida automaticamente (se a repetição estiver ativada). O campo role com valor “free” permite implementar restrições do plano gratuito diretamente nas Security Rules do Firestore, comparando resource.data.role com o nível de acesso necessário.

Geração de miniaturas no upload de imagens

O segundo exemplo — um gatilho de Storage para gerar automaticamente uma miniatura após o upload de uma imagem. A função cria uma cópia reduzida de 200x200 pixels e a salva no caminho do arquivo original com o prefixo thumb_. O processamento de imagens usa a biblioteca sharp, que suporta todos os formatos comuns e funciona no ambiente Node.js sem dependências do sistema.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

A função generateThumbnail verifica o Content-Type do objeto e ignora não-imagens, economizando recursos. Para usar o sharp, a dependência deve ser adicionada ao package.json. A miniatura é criada com o parâmetro fit: “cover”, que corta a imagem do centro para um quadrado de 200x200 pixels. Após a criação, a miniatura é enviada de volta ao mesmo bucket com um nome modificado.

Endpoint HTTPS para uma API pública

O terceiro exemplo — uma função HTTPS implementando um endpoint de API REST para verificar o status do servidor. A função aceita uma requisição GET e retorna JSON com informações sobre o estado dos serviços Firebase conectados ao projeto. Este endpoint é útil para monitoramento e sistemas externos que precisam verificar a disponibilidade do backend antes de enviar dados.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

A função api usa o express Router para roteamento, o que é conveniente ao criar vários endpoints em uma única função. A verificação de saúde escreve no Firestore na coleção _health, permitindo verificar simultaneamente a disponibilidade do Firestore. Para produção, recomenda-se adicionar autenticação de requisição via chave de API ou token do Firebase Auth para evitar abuso do endpoint público.

Casos de uso típicos em aplicativos móveis

Cloud Functions são mais comumente usadas para tarefas que não podem ou não devem ser realizadas no cliente: envio de notificações push, geração de pré-visualizações de imagens enviadas, integração com sistemas de pagamento externos, moderação de conteúdo, sincronização de dados entre o Firebase e serviços de terceiros. O modelo sem servidor torna essas tarefas econômicas: você paga apenas pelo tempo real de execução do código.

A integração com sistemas de pagamento é um cenário típico para aplicativos com compras no aplicativo. O Cloud Functions recebe um webhook do provedor de pagamento (Stripe, PayPal), verifica a assinatura da requisição, atualiza o status da assinatura no Firestore e envia uma confirmação ao usuário. Todo o código é executado no servidor sem risco de adulteração de dados no cliente. De acordo com a documentação do Stripe (2026), o processamento do webhook leva menos de 500 ms.

A moderação inteligente de conteúdo usa um gatilho de Storage do Cloud Function para verificar automaticamente imagens enviadas através do Google Cloud Vision API. A função envia a imagem para a Vision API para detecção de conteúdo inseguro (violência, conteúdo adulto) e, se o limite for excedido, exclui o arquivo e notifica o administrador. Este cenário é crítico para aplicativos UGC com galerias de usuários.

A agregação de dados — Cloud Functions como substituto dos contadores do Firebase Realtime Database. Em vez de ler e escrever um contador no cliente (o que leva a condições de corrida), use um gatilho onWrite do Firestore para atualizações atômicas de campos agregados. Por exemplo, uma função conta o número de curtidas de uma postagem cada vez que um documento é adicionado ou removido na subcoleção /posts/{postId}/likes/{userId} e atualiza o campo likesCount no documento pai.