Tutorial: Deploy de Next.js no Cloudflare Pages do Zero

Por que Cloudflare Pages?

Cloudflare Pages é a opção mais barata, rápida e simples pra hospedar sites estáticos modernos em 2026. Free tier generoso (500 builds/mês, requests ilimitados, bandwidth ilimitado, sem egress fees), CDN em 300+ PoPs, custom domains com SSL automático e integração nativa com Workers.

Comparando com Vercel: Cloudflare é gratuito de verdade, sem trial nem cobrança surpresa. Comparando com Netlify: tem rede edge superior. A trade-off é que algumas features avançadas do Next.js (Server Actions, ISR sob demanda, Image Optimization integrada) precisam de adaptação.

Pra sites estáticos ou apps que cabem em output: "export", Pages é insuperável. É exatamente isso que vamos fazer.

Pré-requisitos

Node.js 20+
Conta Cloudflare (free)
Conta GitHub (opcional, mas recomendado)
Conhecimento básico de Next.js

Passo 1: Criar o projeto Next.js

npx create-next-app@latest meu-site
cd meu-site

Escolha:

TypeScript: Yes
ESLint: Yes
Tailwind: Yes (opcional)
App Router: Yes
src/ directory: Yes
Turbopack: Yes

Passo 2: Configurar para static export

Edite next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  trailingSlash: true,
  images: {
    unoptimized: true,
  },
};

export default nextConfig;

O que cada opção faz:

output: "export" — Next gera HTML estático puro em out/ em vez de exigir servidor Node.
trailingSlash: true — gera /about/index.html em vez de /about.html. Funciona melhor com CDNs.
images: { unoptimized: true } — desabilita o Image Optimization Server (que precisa de runtime). Use next/image normalmente, mas as imagens vão sair como você forneceu.

O que VOCÊ perde com static export

Antes de continuar, saiba: static export não suporta:

API Routes
Middleware
Server Actions
ISR (Incremental Static Regeneration) sob demanda
SSR dinâmico

Se você precisa de qualquer uma dessas features, use Cloudflare Workers + OpenNext (caminho mais avançado, fora deste tutorial) ou Vercel.

Passo 3: Adicionar conteúdo

Edite src/app/page.tsx:

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-black text-white">
      <div className="text-center">
        <h1 className="text-6xl font-bold mb-4">Meu Site</h1>
        <p className="text-xl text-gray-400">Hospedado no Cloudflare Pages</p>
      </div>
    </main>
  );
}

Adicione metadata em src/app/layout.tsx:

export const metadata = {
  title: "Meu Site",
  description: "Site estático no Cloudflare Pages",
};

Passo 4: Build local

npm run build

Você verá uma pasta out/ criada com todos os HTMLs. Pra testar local:

npx serve out

Abra http://localhost:3000 (ou a porta que serve indicar).

Passo 5: Instalar Wrangler

Wrangler é a CLI da Cloudflare. Vamos usar ela pra deploy.

npm install --save-dev wrangler
npx wrangler login

Vai abrir o browser pra você autenticar na Cloudflare.

Passo 6: Criar o projeto no Cloudflare Pages

npx wrangler pages project create meu-site --production-branch=main

Cloudflare cria o projeto e te dá uma URL inicial: https://meu-site.pages.dev.

Passo 7: Deploy

npx wrangler pages deploy out --project-name=meu-site --branch=main

Em ~5 segundos:

✨ Deployment complete!
✅ https://meu-site.pages.dev

Abra a URL no browser. Site no ar, globalmente, em CDN.

Passo 8: Automatizar com npm script

Edite package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && npx wrangler pages deploy out --project-name=meu-site --branch=main"
  }
}

Agora npm run deploy faz build + publish em um comando.

Passo 9: Custom domain

No dashboard Cloudflare:

Pages → meu-site → Custom domains → Set up a custom domain
Digite seu domínio (ex: meusite.com)
Cloudflare detecta se o domínio já está na sua conta. Se sim, configura DNS automaticamente. Se não, te dá um CNAME pra adicionar.

SSL é automático e gratuito. Em ~1 minuto seu site responde no domínio próprio.

Passo 10: CI/CD via GitHub (opcional)

Se você prefere deploy automático em cada push:

Push do projeto pro GitHub.
Cloudflare Pages → Create a project → Connect to Git
Selecione o repo, escolha branch main.
Configure build:
- Framework preset: Next.js (Static HTML Export)
- Build command: npm run build
- Build output: out
Deploy.

A partir daqui, todo git push na main triggera deploy automático. PRs ganham preview deployments com URL única.

Otimizações importantes

Headers e cache

Crie public/_headers:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

/*.css
  Cache-Control: public, max-age=31536000, immutable

/*.js
  Cache-Control: public, max-age=31536000, immutable

Cloudflare aplica esses headers automaticamente.

Redirects

Crie public/_redirects:

/old-page  /new-page  301
/blog/*  https://blog.meusite.com/:splat  302

Env vars

npx wrangler pages secret put MINHA_VAR --project-name=meu-site

Acessível em build time como process.env.MINHA_VAR.

Troubleshooting

Erro: "Project not found" — confirme que o nome do projeto bate com o que você criou.

404 em rotas dinâmicas — você precisa de generateStaticParams() em todas as páginas com [param]. Static export exige.

Imagens quebradas — next/image com unoptimized: true ainda funciona, mas paths relativos podem quebrar. Use paths absolutos começando com /.

Build falha em CI — confirme que node é versão 20+. Configure em Cloudflare Pages → Settings → Environment variables → NODE_VERSION = 20.

Conclusão

Em menos de 15 minutos você tem um site Next.js production-ready hospedado em CDN global, com SSL, custom domain, headers de segurança e CI/CD automático — gastando R$ 0,00. Pra projetos pessoais, landing pages, blogs estáticos, documentação técnica, sites institucionais e MVPs, é difícil bater Cloudflare Pages em 2026.