Criar um pipeline de otimização de imagens com uma CDN
Crie um Worker que transforme uma imagem pública incorporada em três recursos WebP e sirva o HTML que seleciona entre eles. Você pode inspecionar as imagens decodificadas localmente e depois implantar o mesmo código com o Workers Cache habilitado para verificar se requisições repetidas realmente resultam em acertos no cache.
Entender as CDNs de imagens
Um pipeline de imagens precisa tanto de transformação quanto de entrega. Aqui, o
binding Images redimensiona os bytes brutos da imagem
dentro de um Worker. O Workers Cache pode servir
a resposta HTTP resultante sem executar esse Worker novamente. Ele precisa ser habilitado
explicitamente; retornar apenas um cabeçalho Cache-Control não o habilita.
Este exemplo fixa o formato de saída em WebP e expõe apenas três caminhos de imagem. A origem é um PNG sintético de 1.280 × 640 com quatro painéis coloridos. Isso torna o exemplo autossuficiente e fácil de verificar; ele não demonstra qualidade fotográfica nem redução do tamanho do arquivo. Não há uploads, imagens privadas nem URLs de origem arbitrárias.
Preparar o projeto
Os comandos abaixo usam Bash no Linux. As versões testadas são
Node.js 26.12.1, Corepack, Yarn 4.12.0 e
Wrangler 4.154.0. O Node 26 é uma linha de versões com manutenção ativa; essas versões foram fixadas
para reproduzir o exemplo, sem afirmar que outros patches sejam incompatíveis. O Corepack é um
pré-requisito separado no Node 26: siga suas
instruções de instalação se corepack
não estiver disponível. Você também precisa do cURL para verificar o cache após a implantação e de
um navegador compatível com WebP.
Para implantar, use uma conta da Cloudflare com Workers e o binding Images disponíveis, um
subdomínio workers.dev existente e autenticação do Wrangler nessa conta.
O desenvolvimento local abaixo não exige uma implantação na nuvem. Consulte as
opções de autenticação
da Cloudflare antes de implantar; transformações de imagens e requisições ao Worker podem gerar
cobranças.
Em um diretório com permissão de escrita, cole este bloco. Ele se recusa a substituir um diretório
image-pipeline existente e mantém o shell no diretório original:
(
for tool in node corepack; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
mkdir image-pipeline &&
cd image-pipeline &&
mkdir src &&
cat > package.json <<'JSON' &&
{
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"start": "wrangler dev --ip 127.0.0.1 --port 8787",
"build": "wrangler deploy --dry-run --outdir dist",
"deploy": "wrangler deploy"
},
"devDependencies": { "wrangler": "4.154.0" }
}
JSON
printf 'nodeLinker: node-modules\nignorePath: true\nenableScripts: true\nnpmMinimalAgeGate: 0\n' > .yarnrc.yml &&
touch yarn.lock
)
O arquivo de lock local delimita um projeto Yarn próprio para este exemplo. Suas
configurações do Yarn selecionam node_modules
e mantêm o executável do Yarn na versão fixada, em vez de herdar o yarnPath
de um diretório pai. Elas também permitem os scripts de instalação das dependências nativas.
npmMinimalAgeGate: 0 faz este exemplo isolado instalar a versão fixada sem o período de
espera por idade dos pacotes definido em um diretório pai; mantenha a política da sua organização ao
integrá-lo a uma aplicação existente. Nesse mesmo diretório pai, instale e verifique a CLI real:
(cd image-pipeline && corepack yarn install && corepack yarn exec wrangler --version)
O resultado esperado é 4.154.0. Se a instalação falhar, corrija a causa
informada e repita este bloco de instalação no mesmo diretório pai. Mantenha
package.json e o diretório do projeto; executar novamente o bloco de criação
resultaria, corretamente, na recusa do diretório existente. Se a própria criação tiver parado antes
de terminar, inspecione esse diretório antes de continuar ou escolha um novo local vazio.
Configurar a otimização de imagens
Salve este conteúdo como image-pipeline/wrangler.jsonc. Ao implantar, escolha um nome de Worker
que pertença a você e que ainda não tenha usado, para que o exemplo não substitua uma aplicação
existente:
{
"name": "image-pipeline-example",
"main": "src/index.ts",
"workers_dev": true,
"compatibility_date": "2026-10-28",
"images": { "binding": "IMAGES" },
"cache": { "enabled": true, "cross_version_cache": false }
}
A entrada images fornece env.IMAGES. A entrada
separada cache habilita o
Workers Cache para este Worker. As respostas de imagem
abaixo são públicas e podem ser armazenadas em cache por 3.600 segundos; as respostas de HTML e de
falha usam no-store.
Salve o Worker completo como image-pipeline/src/index.ts:
interface ImagesBinding {
input(stream: ReadableStream<Uint8Array>): {
transform(options: { width: number }): {
output(options: { format: 'image/webp' }): Promise<{
response(options?: { headers?: Record<string, string> }): Response
}>
}
}
}
const sourceBase64 =
'iVBORw0KGgoAAAANSUhEUgAABQAAAAKAAgMAAAC+nT0yAAAADFBMVEXIPCgoyGQoPMjctCj/cAxvAAADMUlEQVR42u3TQQ0AIAADsQWPmMQkiOAzQk9CsyXlzfJGdBVAgAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAnymVd4uzwJdGCBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIEKAAAgQIUAABAgQogAABAhRAgAA/6QB65UPMTK7o+gAAAABJRU5ErkJggg=='
const source = Uint8Array.from(atob(sourceBase64), (value) => value.charCodeAt(0))
const page = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Responsive image pipeline</title>
<style>body{margin:0}img{display:block;width:100%;max-width:640px;height:auto}</style>
</head>
<body>
<h1>Responsive image pipeline</h1>
<img src="/image/1280.webp"
srcset="/image/320.webp 320w, /image/640.webp 640w, /image/1280.webp 1280w"
sizes="(max-width: 640px) 100vw, 640px" width="1280" height="640"
alt="Four colored panels used to check image resizing">
</body>
</html>`
const widths: Record<string, number> = {
'/image/320.webp': 320,
'/image/640.webp': 640,
'/image/1280.webp': 1280,
}
export default {
async fetch(request: Request, env: { IMAGES: ImagesBinding }): Promise<Response> {
const url = new URL(request.url)
const notFound = () =>
new Response('Not found', { status: 404, headers: { 'Cache-Control': 'no-store' } })
if (request.method !== 'GET' || url.search !== '') return notFound()
if (url.pathname === '/') {
return new Response(page, {
headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
})
}
if (!Object.hasOwn(widths, url.pathname)) return notFound()
const width = widths[url.pathname]
try {
return (
await env.IMAGES.input(new Blob([source]).stream())
.transform({ width })
.output({ format: 'image/webp' })
).response({
headers: {
'Cache-Control': 'public, max-age=3600',
'X-Image-Run': crypto.randomUUID(),
},
})
} catch {
return new Response('Image transformation unavailable', {
status: 503,
headers: { 'Cache-Control': 'no-store' },
})
}
},
}
Apenas /image/320.webp, /image/640.webp e
/image/1280.webp selecionam uma transformação. Suas dimensões após a decodificação
devem ser 320 × 160, 640 × 320 e 1.280 × 640, respectivamente, com os painéis vermelho e verde
acima dos painéis azul e amarelo. O binding define o tipo de conteúdo da resposta a partir do formato
de saída solicitado. Renomear bytes PNG ou definir um cabeçalho WebP não converteria uma imagem.
Implementar imagens responsivas
Inicie o servidor local a partir do diretório pai:
(cd image-pipeline && corepack yarn start)
Abra http://127.0.0.1:8787/. Você deve ver os quatro painéis ajustados à área de
visualização, até uma largura de exibição de 640 pixels. Abra cada caminho de imagem diretamente
para inspecionar seu conteúdo e suas dimensões. Pare o servidor em primeiro plano com Ctrl+C antes
da próxima etapa. Se a porta 8787 estiver ocupada, pare o outro serviço que a utiliza ou escolha
outra porta no script start antes de iniciar este exemplo.
O sizes do HTML corresponde a esse layout CSS:
100vw até 640 pixels e, depois, 640px.
Seus descritores 320w, 640w e
1280w descrevem as larguras reais dos recursos, em vez das larguras de
exibição. Os atributos width e height
reservam uma proporção de 2:1, enquanto src fornece a imagem padrão.
Consulte as regras de seleção de imagens do HTML.
Inspecione a requisição da imagem escolhida no painel de rede do navegador. Uma área de visualização de 320 pixels com DPR 1, uma de 800 pixels com DPR 1 e uma de 640 pixels com DPR 2 exercitam necessidades diferentes de recursos. Use novos contextos de navegador ao compará-las: a seleção pode depender do navegador, da proporção de pixels do dispositivo e dos recursos em cache. A marcação oferece opções ao navegador; ela não obriga todos os navegadores a fazer uma única escolha universal.
O Wrangler local usa uma implementação offline limitada do Images que permite o redimensionamento e o formato explícito deste exemplo. Ele verifica a página e as transformações, mas não comprova um acerto no cache da Cloudflare após a implantação. A Cloudflare documenta essas limitações do binding local.
Implantar e observar o cache
Faça o build primeiro. Uma execução de teste bem-sucedida grava o Worker empacotado em
image-pipeline/dist/index.js sem fazer seu upload. Repetir o build atualiza esse diretório
de saída descartável:
(cd image-pipeline && corepack yarn build)
Depois de confirmar sua conta, a autenticação e o nome de Worker ainda não utilizado, implante a partir do mesmo diretório pai:
(cd image-pipeline && corepack yarn deploy)
Abra a URL workers.dev exibida pelo Wrangler e verifique novamente a página e
as três URLs de imagem. Substitua a origem nos dois comandos abaixo pela origem dessa URL. São
requisições GET completas que descartam o corpo e exibem os cabeçalhos; o cURL não usa o cache de
imagens de um navegador:
(
command -v curl >/dev/null 2>&1 || { printf 'Install cURL first\n' >&2; exit 1; }
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp' &&
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp'
)
Procure CF-Cache-Status: HIT em uma requisição repetida e compare
X-Image-Run com a resposta anterior. Um acerto no cache deve manter o marcador
gerado quando o Worker produziu essa resposta. Um cabeçalho Cache-Control,
bytes de imagem idênticos ou um marcador estável, isoladamente, não comprovam um acerto no cache.
Se o status estiver ausente, verifique a configuração cache.enabled implantada;
ausências repetidas no cache exigem verificar a política da resposta e a chave de cache. O
guia de depuração de cache da Cloudflare explica esses
status. Não trate uma prévia local como evidência equivalente.
Isso comprova uma observação do cache, não um benchmark de velocidade ou largura de banda. Meça os bytes reais e as métricas da página com imagens representativas antes de afirmar que houve uma melhoria de desempenho.
Manter os limites do exemplo público
Todas as imagens aqui são públicas, e o Worker aceita um conjunto fixo de caminhos. Mantenha esse limite ao experimentar: aceitar URLs arbitrárias acrescentaria um problema diferente de busca de imagens de origem e controle de acesso. Não use imagens confidenciais nesse fluxo de respostas públicas que podem ser armazenadas em cache. A entrega privada precisa de seu próprio projeto de autorização e cache.
Para uma biblioteca de imagens real, substitua a origem sintética somente depois de escolher como
os originais serão armazenados e como o acesso a eles será autorizado. Em seguida, verifique as
larguras de saída após a decodificação antes de informá-las em srcset.
Processamento e entrega gerenciados são outra opção; conheça o
Smart CDN da Transloadit.
Prefere não executar isso por conta própria?
O Smart CDN da Transloadit transforma e entrega arquivos em tempo real.
