Como hospedar um projeto Next.js fora do localhost

Rodar npm run dev na sua máquina é só o começo. Para outras pessoas acessarem o site, o Next.js precisa ser compilado para produção e ficar em um servidor ligado o tempo todo, com a porta, as variáveis e a versão do Node corretas.

O Next.js não depende de nenhuma plataforma específica. A documentação oficial descreve três formas de hospedar: um servidor Node.js, uma imagem Docker ou arquivos HTML estáticos. A escolha depende dos recursos de servidor que o seu projeto usa.

Qual modo de hospedagem escolher?#

Escolha o export estático só se o site funcionar sem código no servidor. A documentação lista o que não é suportado nesse modo: Server Actions, cookies, rewrites, redirects e headers do next.config, proxy (antigo middleware), ISR, Draft Mode, rotas dinâmicas sem generateStaticParams() e o otimizador de imagens padrão. Se você usa qualquer um deles, fique com o servidor Node.js. Para entender o formato estático em geral, veja o que é um site estático.

O que você precisa antes de começar?#

• Uma versão recente do Node.js. A documentação do Next.js informa o mínimo exigido. Em produção, use a versão LTS ativa do Node.js; o calendário oficial mostra qual é.
• Scripts no package.json, que o create-next-app já gera:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

• Um lockfile commitado (package-lock.json, pnpm-lock.yaml) para instalar as mesmas versões em qualquer máquina.
• Um lugar para rodar: uma VPS, um container ou uma plataforma de hospedagem. Veja a diferença em VPS vs plataforma de nuvem.

Como hospedar como servidor Node.js?#

É o caminho que suporta todos os recursos. No servidor (ou no CI), rode:

npm ci
npm run build
npm run start

O next build gera a pasta .next e mostra a tabela de rotas, onde ○ é estática e ƒ é renderizada sob demanda. O next start sobe o servidor de produção em 0.0.0.0, na porta 3000 por padrão. Para mudar a porta, use a variável PORT ou a flag -p:

PORT=8080 npm run start
npx next start -p 8080

PORT precisa estar no ambiente do processo. Colocar no .env não funciona, porque o servidor HTTP sobe antes de o Next.js carregar esse arquivo.

Com next start, a otimização de imagens do next/image funciona sem configuração. Em Linux baseado em glibc, a documentação avisa que ela pode exigir um ajuste do alocador de memória para evitar uso excessivo de RAM.

Como gerar standalone ou export estático?#

Standalone, para um deploy menor#

O modo standalone copia só os arquivos que o servidor realmente usa, inclusive os trechos necessários de node_modules. Ative no next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Depois do next build, a pasta .next/standalone tem um server.js mínimo. Ele não copia public nem .next/static por padrão. Copie você mesmo:

npm run build
cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js

O server.js lê PORT e HOSTNAME:

PORT=8080 HOSTNAME=0.0.0.0 node .next/standalone/server.js

Em monorepos, o rastreamento de arquivos parte da pasta do projeto. Se faltarem arquivos que ficam fora dela, defina outputFileTracingRoot no next.config. Para empacotar tudo numa imagem, veja como colocar um app em Docker.

Export estático, para sites sem código no servidor#

Se o site é só conteúdo, mude a configuração:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
};

export default nextConfig;

O next build passa a criar a pasta out com um HTML por rota, mais CSS e JS. Qualquer servidor de arquivos estáticos serve esse conteúdo. Se você usa next/image, defina um loader personalizado em images, já que o otimizador padrão exige servidor.

Como configurar variáveis de ambiente?#

Por padrão, variáveis ficam disponíveis só no servidor. As que começam com NEXT_PUBLIC_ são inseridas no JavaScript durante o next build: mudar o valor depois exige compilar de novo. Já variáveis lidas no servidor durante a renderização dinâmica (por exemplo, depois de await connection()) são avaliadas em tempo de execução, então a mesma build serve vários ambientes.

Nunca coloque segredos em variáveis NEXT_PUBLIC_, porque elas vão para o navegador. O padrão geral está em o que são variáveis de ambiente.

Como verificar se deu certo?#

1. Logs: o next start imprime o endereço e a porta, sem erros em seguida.
2. Requisição: abra a página inicial e uma rota dinâmica pelo endereço público.
3. Assets: no navegador, confirme que os arquivos de /_next/static/ carregam com status 200.
4. Reinício: reinicie o processo e veja se o site volta sozinho. O servidor do Next.js termina as requisições em andamento ao receber SIGTERM ou SIGINT.

Se houver um proxy reverso como o nginx na frente, desative o buffering para o streaming funcionar (por exemplo, com o header X-Accel-Buffering: no).

Quais erros são mais comuns?#

• Site abre local, mas não pelo endereço público: confira o host e a porta em que o processo escuta. O next start já escuta em 0.0.0.0 por padrão, mas o server.js do standalone escuta no endereço da variável HOSTNAME. Defina HOSTNAME=0.0.0.0 e a PORT no comando de início.
• Página sem CSS ou imagens quebradas no standalone: você esqueceu de copiar public e .next/static.
• Failed to find Server Action: com várias instâncias, cada build gera uma chave de criptografia própria. Defina a mesma NEXT_SERVER_ACTIONS_ENCRYPTION_KEY em todas, na hora do build.
• Variável NEXT_PUBLIC_ com valor antigo: ela foi embutida no build. Recompile.
• Processo morto durante next build: costuma ser falta de memória. Aumente a RAM disponível ou compile fora do servidor, no CI.
• Conteúdo desatualizado com mais de uma instância: o cache de páginas fica no disco de cada instância. Para compartilhar, configure um cache handler, como descreve a documentação.

Como fazer isso na Square Cloud#

Na Square Cloud o deploy é self-service: você envia o projeto e controla a configuração. O Node.js está entre diversos runtimes, e o runtime de sites estáticos é uma opção para a pasta out do export: nele o nginx fica sempre no ar servindo os arquivos, sem código seu rodando no servidor. Você envia por upload de ZIP no painel, pela CLI, pelo GitHub (um push faz o deploy) ou pela extensão do VS Code.

A plataforma não tem etapa de build. Rode o next build num CI externo, como o GitHub Actions, e envie o resultado, ou coloque o build no comando de início: npm run build && npm start. Nesse caso, tudo o que o build usa precisa estar em dependencies, porque as devDependencies não são instaladas. O servidor deve escutar em 0.0.0.0, na porta da variável PORT, que o next start já lê.

O arquivo squarecloud.app (nome, arquivo principal, memória e versão) é opcional: o painel o gera no deploy, ou você o escreve na raiz do projeto. As variáveis de ambiente ficam por aplicação, no painel, na API, na CLI ou no VS Code. O painel importa um .env, e a mudança vale no próximo restart, exceto nas NEXT_PUBLIC_, que só mudam com um novo next build.

A aplicação roda num container sempre ligado. O reinício automático vem ligado no deploy pelo painel e só age quando o processo encerra com erro. A RAM do plano é um pool compartilhado entre as suas aplicações, com mínimo de 512 MB por aplicação web.

Toda aplicação web ganha um subdomínio *.squareweb.app com HTTPS, e o domínio personalizado está disponível a partir do plano Standard (veja como usar um domínio personalizado). Os planos são pagos, começam em R$ 12,49 por mês e todos incluem analytics web sem cookies. Os detalhes estão na página de sites.