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
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.
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
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.