Resposta rápida
Desde 4 de setembro de 2026, o Cloudflare Workers aceita bundles de até 64 MiB sem compressão nos planos Free e Paid. Os antigos limites de 3 MB compactados no plano gratuito e 10 MB compactados no plano pago foram removidos.
Para saber se o projeto cabe, execute wrangler deploy --outdir bundled/ --dry-run e leia o valor Total Upload. Esse é o tamanho sem compressão usado na validação. O valor gzip continua aparecendo no resultado, mas agora serve apenas como referência.
Como medir o bundle antes do deploy
O modo dry-run cria localmente a mesma saída que o Wrangler prepararia para enviar, sem publicar uma nova versão. Isso permite conferir o tamanho e examinar o código final antes de alterar produção.
Execute o comando na raiz do projeto e mantenha a mesma versão do Wrangler usada no pipeline. Se o computador e o CI usam versões ou etapas de build diferentes, eles podem produzir bundles diferentes.
- Instale ou selecione a versão do Wrangler usada pelo projeto.
- Execute: npx wrangler deploy --outdir bundled/ --dry-run
- Localize Total Upload no resumo final.
- Compare o valor com 64 MiB; não use o número gzip como critério de aprovação.
- Abra a pasta bundled para conferir quais módulos e arquivos realmente entrariam no envio.
Total Upload e gzip não são a mesma coisa
Total Upload representa o tamanho sem compressão do bundle. Gzip mostra quanto a mesma saída ocupa compactada durante a transferência. Um projeto pode ter gzip pequeno e ainda ultrapassar o limite quando descompactado.
Essa distinção é importante para pipelines antigos. Uma regra de CI que compara apenas o tamanho compactado pode aprovar um artefato que a plataforma rejeita. Atualize o controle para registrar Total Upload e deixe uma margem para o crescimento entre versões.
O que costuma aumentar o tamanho do Worker
Dependências que trazem código para vários ambientes, pacotes duplicados, dados binários, arquivos de configuração extensos e conteúdo estático importado diretamente podem inflar a saída. O tamanho do repositório ou de node_modules, isoladamente, não informa o que será enviado: a medição deve ocorrer depois do bundling.
O Wrangler usa esbuild por padrão e resolve módulos npm declarados pelo projeto. Código limitado ao ambiente de desenvolvimento pode ser removido quando depende corretamente de NODE_ENV, porque o bundler define production durante wrangler deploy e wrangler build.
Como reduzir o bundle com segurança
Comece pela saída do dry-run, não por exclusões aleatórias. Remova apenas bibliotecas, módulos e dados que não participam do comportamento necessário. Depois de cada alteração, rode os testes, gere novamente o bundle e compare o Total Upload.
A documentação recomenda mover configuração, arquivos estáticos e dados binários para KV, R2, D1 ou Workers Static Assets quando eles não precisam fazer parte do código. Funcionalidades independentes também podem ser separadas em Workers diferentes conectados por Service Bindings.
- Remova imports e dependências que não são usados em produção.
- Evite incluir SDKs completos quando o pacote oferece uma entrada menor compatível com o runtime.
- Mova imagens, documentos e outros arquivos estáticos para o recurso de armazenamento adequado.
- Revise regras que incluem módulos adicionais e confirme se os globs não capturam diretórios desnecessários.
- Divida responsabilidades muito diferentes entre Workers somente quando houver um limite operacional claro.
- Gere o dry-run novamente e confirme o ganho no Total Upload.
Quando usar módulos externos e partial bundling
Com find_additional_modules e regras explícitas, o Wrangler pode enviar arquivos compatíveis como módulos separados em vez de incorporá-los ao arquivo principal. Isso é útil para módulos carregados dinamicamente e para tipos como texto, HTML, SQL, binário e WebAssembly.
Separar um módulo não faz os bytes desaparecerem do envio total. A configuração ajuda a controlar carregamento e empacotamento, mas todos os arquivos publicados ainda precisam respeitar os limites aplicáveis. Teste imports dinâmicos em um ambiente isolado para evitar falhas que só aparecem em execução.
Por que desativar o bundling não é a primeira correção
A opção --no-bundle existe para projetos que já produzem artefatos compatíveis com o Workers usando outra ferramenta. A Cloudflare não recomenda desativar o bundling na maioria dos casos, porque recursos como minificação e injeção de polyfills deixam de ser aplicados pelo Wrangler.
Usar --no-bundle apenas para contornar uma medição pode trocar um erro visível de tamanho por imports ausentes ou incompatibilidades em produção. Só adote essa rota quando o build personalizado já controla módulos, runtime e arquivos enviados.
Bundle grande também pode afetar a inicialização
O limite maior não garante inicialização rápida. O Worker precisa analisar o código e executar o escopo global em até um segundo. A documentação alerta que bundles grandes e inicialização cara fora dos handlers podem aumentar esse tempo.
Quando a validação retorna Script startup exceeded CPU time limit, código 10021, o problema não é necessariamente o teto de 64 MiB. Use o perfil gerado pelo Wrangler, evite trabalho pesado no escopo global e mova cálculos para o build ou para o handler quando fizer sentido.
Tamanho, memória e CPU são limites diferentes
O tamanho do bundle é validado no deploy. Memória e CPU são consumidas quando o Worker executa. Um projeto abaixo de 64 MiB ainda pode ultrapassar 128 MB de memória, exceder o tempo de CPU do plano ou falhar por inicialização lenta.
Leia a mensagem completa e consulte Metrics e logs antes de otimizar. Worker exceeded resource limits durante uma requisição aponta para CPU ou memória, enquanto uma rejeição antes da publicação exige revisar a validação do upload ou da inicialização.
Checklist para o pipeline de CI
Inclua um dry-run antes da etapa que publica. Registre a versão do Wrangler, o Total Upload e a variação em relação ao último build aprovado. O objetivo não é usar os 64 MiB até o último byte, mas detectar uma dependência inesperada antes de ela bloquear a entrega.
- Fixe uma versão conhecida do Wrangler no lockfile e no CI.
- Execute o mesmo build de produção usado no deploy.
- Rode wrangler deploy --outdir bundled/ --dry-run.
- Falhe o pipeline em um limite interno abaixo de 64 MiB.
- Guarde o resumo de tamanho como artefato ou log do build.
- Só publique depois dos testes e da revisão da diferença de tamanho.
Limites deste diagnóstico
Este guia foi verificado em 7 de setembro de 2026. O limite de 64 MiB sem compressão vale para Workers Free e Paid conforme a documentação oficial consultada. Limites, comandos e comportamento do bundler podem mudar; confirme as páginas oficiais antes de alterar o pipeline.
O dry-run mostra o que o Wrangler atual prepararia para enviar, mas não prova que a aplicação funciona corretamente no runtime. Testes, compatibilidade de APIs, bindings, inicialização e observabilidade continuam necessários.
Próxima ação útil
Execute o dry-run no mesmo ambiente do seu deploy e registre Total Upload. Se estiver perto do teto, examine a pasta gerada, remova uma dependência ou ativo grande por vez e meça novamente. Se o envio passar, mas o site continuar indisponível, consulte o status oficial da Cloudflare e teste DNS, HTTPS e resposta HTTP antes de atribuir a falha ao bundle.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Deploy larger Workers — up to 64 MiB for both free and paid plansCloudflare Changelog
- Workers platform limitsCloudflare Docs
- Wrangler bundlingCloudflare Docs
- Wrangler commandsCloudflare Docs
- Cloudflare StatusCloudflare