Esta é a Parte 2 da minha série de migração do WordPress headless. Implantação de WordPress headless é onde os problemas reais começam, porque DNS, SSL, imagens, formulários e redirects quebram de formas diferentes. Na Parte 1, eu reconstruí o frontend em um dia com Claude Code, Stitch MCP e Next.js. Neste artigo, eu mostro os problemas de implantação que enfrentei, como corrigi-los, e por que a IA ainda precisava de julgamento humano.
O Problema de Implantação de WordPress Headless Sobre o Qual Ninguém Fala
Construir o frontend é a parte fácil. Na minha experiência, implantação de WordPress headless fica difícil no momento em que você divide um site em dois sistemas: Vercel para o frontend e WordPress para o backend. Você não tem mais uma stack simples. Você passa a ter DNS, certificados, URLs de mídia, endpoints REST e acesso de admin puxando em direções diferentes.
Quando `optagonen.se` mudou para o Vercel, cada requisição que antes ia para o WordPress começou a cair no novo frontend. Isso quebrou GraphQL, uploads, Contact Form 7 e acesso ao admin de uma vez. Se você está planejando sua própria implantação de WordPress headless, precisa projetar esses pontos de quebra antes de trocar o DNS.
Eu testei isso em uma migração real de produção, não em um ambiente de sandbox. A lição foi clara: o código ficou pronto rápido, mas a infraestrutura levou tempo.
Dividindo DNS para uma Implantação de WordPress Headless
A correção mais limpa foi dar ao WordPress seu próprio subdomínio: `wp.optagonen.se`. Isso separou o frontend e o backend sem me forçar a fazer reverse proxy de tudo por uma única origem. Também deixou a arquitetura mais fácil de raciocinar na hora de depurar SSL e entrega de mídia.
| Domínio | Aponta para | Finalidade |
|---|---|---|
| --- | --- | --- |
| `optagonen.se` | Vercel | Frontend no Next.js |
| `wp.optagonen.se` | Servidor de origem | Backend do WordPress |
Eu adicionei `wp.optagonen.se` como um alias no Hestia, apontei o registro DNS A para o IP da origem e atualizei a variável de ambiente do frontend:
Essa parte é simples no papel. Na prática, a implantação de WordPress headless expôs uma reação em cadeia. Todo sistema que assumia o domínio antigo precisava de um novo destino.
Implantação de WordPress Headless e Falhas de Certificado SSL
A primeira coisa que quebrou foi o SSL. O certificado antigo do Let's Encrypt só cobria `optagonen.se` e `www.optagonen.se`, então `https://wp.optagonen.se` falhou imediatamente. Isso é comportamento esperado. O Let's Encrypt valida a propriedade do domínio por hostname, e o navegador rejeita a conexão se o certificado não corresponder.
A renovação embutida do Hestia falhou porque ele ainda tentava validar o domínio principal via HTTP-01, mas o domínio principal agora apontava para o Vercel. O Certbot falhou por outro motivo: o Hestia interceptou o desafio ACME e retornou seu próprio thumbprint em vez do do Certbot. Esse é o tipo de conflito que a IA não consegue inferir a partir de primeiros princípios. Você precisa saber como o painel se comporta.
Eu corrigi isso movendo temporariamente a configuração do desafio ACME do Hestia para fora do caminho include do nginx, emitindo um certificado apenas para `wp.optagonen.se` e, depois, copiando os arquivos renovados de volta para o diretório SSL do Hestia. Também adicionei um hook de renovação para o processo continuar automático.
Para ter confiança, eu me apoiei na documentação oficial do Let's Encrypt e do Certbot. Isso ajudou a confirmar o fluxo ACME antes de eu mexer novamente na produção.
Por que a Implantação de WordPress Headless Rejeitou o Subdomínio
Assim que o SSL funcionou, o WordPress ainda não aceitou o novo host. Em vez de retornar dados de GraphQL, ele redirecionou para `/wp-signup.php`. Isso me disse que o WordPress não gostou do header de host recebido.
A correção foi uma única diretiva do nginx:
Essa linha fez o WordPress se comportar como se as requisições ainda estivessem vindo do domínio principal, enquanto o navegador permanecia em `wp.optagonen.se`. Em uma implantação de WordPress headless, esse tipo de normalização de host importa mais do que as pessoas esperam. O WordPress é bem opinativo sobre URLs do site.
Eu já vi essa mesma classe de problema aparecer em outras migrações também. O frontend funciona, o backend responde e, então, um header de host que não bate silenciosamente quebra o fluxo de sessão.
As Imagens Quebraram Depois da Implantação de WordPress Headless
Depois do deploy, toda imagem retornou um erro 502. Isso aconteceu porque as URLs de mídia do WordPress ainda apontavam para `/wp-content/uploads/...`, e esses caminhos agora eram resolvidos contra o Vercel em vez do servidor de origem. Na minha configuração, o problema veio de dois lugares: URLs hardcoded em arquivos estáticos e URLs dinâmicas retornadas pelo WPGraphQL.
Eu corrigi primeiro as URLs hardcoded. Substituí todas as referências `https://optagonen.se/wp-content/uploads/` por `https://wp.optagonen.se/wp-content/uploads/` em seis arquivos. Isso cobriu cerca de 70 caminhos de imagens.
Depois, corrigi as URLs dinâmicas de GraphQL com uma rewrite no Next.js:
Isso manteve o frontend limpo e evitou reescrever dados de mídia dentro do WordPress. Também deixou a implantação de WordPress headless mais fácil de manter, porque o navegador ainda requisita o mesmo caminho enquanto o servidor faz o proxy.
Se você quiser se aprofundar nesse tipo de design de sistema, eu recomendo ler meu workflow de migração de WordPress com IA→ e meu pipeline de conteúdo multi-agent→. Esses posts mostram como eu estruturo sistemas de infraestrutura e conteúdo em torno de automação.
Formulários de Contato, IDs e o Último Perigo da Implantação
O Contact Form 7 parecia estar tudo bem no começo, mas o formulário parou de funcionar porque o ID no frontend estava errado. O ID padrão do formulário era `1`, mas o formulário real no WordPress era `8`. Uma checagem rápida via API confirmou isso.
Foi um ajuste pequeno, mas importa. Em uma implantação de WordPress headless, um ID errado pode fazer um formulário que funciona parecer quebrado mesmo quando o backend está saudável. Eu defini `CF7_FORM_ID=8` e o formulário voltou a ficar online imediatamente.
É por isso que eu sempre testo o fluxo completo manualmente:
Essa sequência detecta problemas mais rápido do que ficar adivinhando apenas pelos logs.
O que a IA Ajudou e o que Ela Não Percebeu
Claude Code me ajudou a ir rápido, mas não substituiu entender. Ele lidou bem com as partes repetitivas: buscar em arquivos de configuração, gerar snippets do nginx, ajudar com comandos do certbot e substituir URLs de imagens em lote. Ele também manteve a cadeia de erros na memória, o que economizou tempo quando uma correção criava outro problema.
No entanto, a IA não conseguiu decidir a arquitetura completa. Ela não sabia que o Hestia interceptaria requisições ACME. Ela não sabia quando usar um subdomínio em vez de um reverse proxy. E ela não sabia a ordem das operações que evitaria downtime.
Esse é o valor real da IA em uma implantação de WordPress headless: ela acelera o diagnóstico, mas você ainda precisa da pessoa que entende a stack. Eu uso o mesmo princípio no meu trabalho construindo sistemas de automação com IA para e-commerce→ e no meu trabalho com pipeline de conteúdo.
Arquitetura Final Depois da Implantação
Depois das correções, a stack ficou dividida de forma limpa:
| Componente | Local | Finalidade |
|---|---|---|
| --- | --- | --- |
| Frontend Next.js | Vercel | Serve páginas e faz routing |
| WordPress + WPGraphQL | `wp.optagonen.se` | API de conteúdo e armazenamento de mídia |
| Contact Form 7 | `wp.optagonen.se` | Tratamento de formulários |
| Proxy de imagem | Regra de rewrite do Next.js | Roteia uploads para a origem |
| SSL do frontend | Vercel | Gerenciamento automático |
| SSL do backend | Certbot + renewal hook | Certificados renovados automaticamente |
Essa estrutura é estável e fácil de depurar. Ela também mantém o frontend rápido enquanto preserva o fluxo editorial dentro do WordPress. Em uma implantação de WordPress headless, esse equilíbrio é o objetivo.
Lições Desta Implantação de WordPress Headless
Aqui está o que eu aprendi com a migração:
Essas lições vieram de uma mudança real em produção, não de um tutorial. Por isso, agora eu aloco tanto tempo para implantação quanto eu aloco para construir.
Conclusão
Implantação de WordPress headless não é difícil por causa do código. É difícil porque DNS, SSL, mídia e headers de host dependem um do outro. Nesta migração, eu corrigi a divisão por subdomínio, a validação de certificado, a entrega de imagens e o Contact Form 7, e aprendi exatamente onde a IA ajuda e onde ela para.
Se você está planejando sua própria migração, leia primeiro a reconstrução do frontend, teste o fluxo de certificado cedo e verifique cada caminho de mídia antes de colocar no ar. Depois, verifique o site ao vivo, confirme os formulários e garanta que o backend ainda se comporte do jeito que o WordPress espera.
Se você quiser mais detalhamentos práticos de implantação, continue lendo os posts relacionados e compare com sua própria stack. Essa é a forma mais rápida de evitar erros na sua próxima implantação de WordPress headless.
Sugestão de texto alternativo para imagem: