Ir para o conteúdo
Promovaweb

Cloudflare Workers: código que roda a cada requisição

Um Worker é um programa em JavaScript, TypeScript, Python ou Rust que a Cloudflare executa nos data centers dela a cada requisição recebida. O runtime chama a função fetch() do seu código dentro de um isolate do V8, criado num processo que já está rodando, por isso o Worker responde sem servidor seu ligado e sem a espera de partida de uma máquina virtual.

Ficha e sumário da página

Referência técnica
Wrangler 4.162.0
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Uma função que recebe a requisição e devolve a resposta
  2. Isolates no lugar de containers
  3. Assets estáticos e o arquivo de configuração
  4. Bindings ligam o Worker aos outros serviços
  5. Limites do plano Free e do pago

Uma função que recebe a requisição e devolve a resposta

O formato básico de um Worker é um módulo que exporta um objeto com a função fetch. Quando um data center da Cloudflare recebe uma requisição para o subdomínio workers.dev do Worker ou para um domínio seu ligado a ele, o runtime chama essa função com três argumentos: a requisição, o objeto env com os bindings e o objeto ctx com o ciclo de vida da execução. A resposta ao visitante é o objeto Response que o código devolve.

export default {
async fetch(request, env, ctx) {
return new Response('Hello World!');
},
};

No exemplo, tirado da documentação oficial, a função só devolve um texto. A mesma função lê o caminho da URL, consulta um bucket, chama uma API externa com fetch() ou repassa a requisição para outro serviço. O runtime implementa as APIs padrão dos navegadores, como Request, Response, URL e crypto, então o código se parece com o JavaScript que você escreve para o navegador.

Isolates no lugar de containers

O que separa um Worker de uma função num servidor comum é o lugar onde o código roda. Cada máquina da rede tem uma instância do runtime dos Workers, que executa centenas ou milhares de isolates do V8 ao mesmo tempo. O V8 é o mesmo motor de JavaScript do Chromium e do Node.js. O isolate é um ambiente leve, com memória separada dos demais, criado dentro de um processo que já está rodando.

A documentação compara esse modelo com os provedores que sobem um container ou uma máquina virtual para cada função. Segundo a página oficial, um isolate abre cerca de cem vezes mais rápido que um processo do Node num container ou numa máquina virtual e consome uma ordem de grandeza menos memória na partida. A documentação registra que esse modelo elimina a partida a frio do modelo com máquina virtual.

Em troca, o isolate não tem vida longa garantida. A plataforma pode descartá-lo por falta de recurso na máquina, por um script suspeito ou por limite estourado. A documentação recomenda não guardar estado mutável no escopo global do código, porque nada garante que duas requisições cheguem à mesma instância do Worker.

Assets estáticos e o arquivo de configuração

Além de rodar código, um Worker serve os arquivos de um site. A chave assets do arquivo de configuração do Wrangler aponta a pasta do build, que o Wrangler envia junto com o código em cada deploy. Por padrão, a requisição que corresponde a um arquivo dessa pasta recebe o arquivo sem executar o código, enquanto os caminhos sem arquivo seguem para a função fetch. Na primeira situação, a requisição é gratuita e não tem limite.

O website da Promovaweb usa esse recurso com o Worker na frente de tudo. O arquivo abaixo resume as chaves do wrangler.jsonc dele, sem os blocos de observabilidade:

website/wrangler.jsonc

Worker

name:
Nome permanente do Worker no painel e no subdomínio workers.dev.
main:
Arquivo com a função fetch, aqui ./src/worker.mjs, que aplica os redirecionamentos.
compatibility_date:
Data que fixa o comportamento do runtime, aqui 2026-06-01.

Assets

directory:
Pasta publicada, aqui ./dist, gerada pelo build do Astro.
binding:
Nome do binding no código, ASSETS, usado em env.ASSETS.fetch().
run_worker_first:
Com true, toda requisição passa pela função antes do arquivo.
not_found_handling:
Com 404-page, um caminho sem arquivo recebe o 404.html mais próximo.
html_handling:
Com force-trailing-slash, as páginas respondem sempre com a barra final.
Chaves do arquivo de configuração do Worker que publica o website da Promovaweb. O arquivo não guarda token nem senha: a autenticação do deploy fica na integração com o GitHub.

Com run_worker_first ligado, cada requisição ao website executa o Worker, que confere se o caminho tem um redirecionamento permanente e só depois busca o arquivo pelo binding ASSETS. A documentação de cobrança avisa que, no plano Free, os caminhos marcados para rodar o Worker antes recebem erro 429 quando a cota diária de requisições acaba, no lugar do arquivo estático.

Bindings ligam o Worker aos outros serviços

O objeto env traz os bindings declarados no arquivo de configuração. Um binding é a ligação entre o Worker e um recurso da plataforma, como um bucket do R2, um banco D1, um namespace do KV, uma fila ou os próprios assets estáticos. O código chama métodos do binding, como env.MEU_BUCKET.get(chave), sem guardar chave de API no código. A documentação registra que os bindings têm desempenho melhor e menos restrições que as APIs REST, que existem para aplicações de fora dos Workers.

As variáveis de ambiente e os segredos chegam ao código pelo mesmo objeto env. Para a documentação, um segredo é um binding de texto criptografado feito para guardar chaves de API e tokens. A mesma página recomenda não colocar valores sensíveis nas variáveis comuns do arquivo de configuração. Assim o repositório do Worker não carrega a chave de uma API externa.

Limites do plano Free e do pago

RecursoPlano FreePlano pago
Requisições100.000 por diaSem limite diário
CPU por requisição10 msAté 5 min, com 30 s como padrão
Memória por isolate128 MB128 MB
Subrequisições50 por requisição10.000 por requisição
Arquivos de assets20.000 por versão, até 25 MiB cada100.000 por versão, até 25 MiB cada

O tempo de CPU mede só o processamento do seu código. A espera por um fetch(), por uma leitura do R2 ou por uma consulta a um banco não entra na medida. A documentação cita uma média de 2,2 ms de CPU por requisição entre os Workers. Quando uma requisição passa do limite de CPU, a Cloudflare devolve ao visitante o erro 1102, com a mensagem Worker exceeded resource limits. O limite de memória vale para o isolate inteiro, que pode atender várias requisições ao mesmo tempo.

Para ligar o Worker a um domínio, o recurso Custom Domains cria os registros DNS e emite o certificado sem que você mexa no DNS. A página DNS e domínios explica o que acontece com esse registro. O deploy pelo GitHub, que publica cada versão do Worker, está em Builds e deploy pelo GitHub.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.