Como migrar do Hugo, Hexo ou Next.js para o Astro: guia detalhado para concluir em 3 dias

Introdução

Sempre que eu abria meu blog e via aquelas páginas carregando devagar, ficava incomodado. Às vezes eu queria adicionar uma pequena funcionalidade a um template do Hugo e acabava esbarrando em uma sintaxe nada amigável. Em outros casos, um blog estático feito com Next.js gerava arquivos JavaScript enormes. Para um simples blog, por que carregar tanto código?

Eu também já enfrentei esses problemas. Até ouvir falar do Astro, um framework que promete levar o desempenho do site ao máximo e chegar facilmente a 100 pontos no PageSpeed Insights. No começo, fiquei desconfiado. Mas, ao ver cada vez mais desenvolvedores relatando que a migração não era tão complicada, comecei a considerar a ideia.

Mesmo assim, a migração levantava três preocupações:

1. A migração vai dar muito trabalho? Tenho dezenas ou centenas de artigos; preciso alterar um por um?
2. Ela vai afetar o SEO? O que acontece se a estrutura das URLs mudar?
3. Quais problemas preciso conhecer de antemão? Não quero ficar travado no meio do processo.

Se você tem as mesmas dúvidas, este artigo foi feito para você. Vou apresentar o caminho completo para migrar de três frameworks populares — Hugo, Hexo e Next.js — para o Astro, incluindo as operações de cada etapa, problemas comuns e boas práticas. Segundo os relatos de desenvolvedores que reuni, todo o processo leva apenas de 1 a 3 dias.

Por que vale a pena migrar para o Astro

Primeiro, vamos entender por que tanta gente está migrando para o Astro. Não se trata de seguir uma moda, mas de obter benefícios concretos.

Principais vantagens do Astro

Estratégia Zero JavaScript

A principal característica do Astro é ter “zero JS por padrão”. Isso mesmo: as páginas que ele gera não incluem JavaScript por padrão. Para blogs e sites de documentação, cujo foco é o conteúdo, essa abordagem é uma solução definitiva de otimização de desempenho.

Um desenvolvedor japonês relatou que, depois de migrar do Next.js para o Astro, sua pontuação no PageSpeed Insights saltou de 85 para 100 — e chegou a 100 em todos os testes. Esse avanço veio principalmente de dois fatores:

• remoção do JavaScript necessário para hydration;
• CSS inline, reduzindo o número de requisições de rede.

Arquitetura de Islands

Sites modernos ainda precisam de alguns recursos interativos, como comentários, busca e um botão para alternar o tema. A solução do Astro é a arquitetura de Islands: você pode adicionar JavaScript somente a componentes interativos específicos dentro de uma página HTML estática, mantendo todo o restante puramente estático.

É como uma ilha cercada por um oceano estático: só existe vida dinâmica na ilha.

Experiência moderna de desenvolvimento

Quem já usou Hugo sabe como a sintaxe dos templates pode ser difícil. O Astro é bem diferente: a sintaxe dos arquivos .astro é muito parecida com JSX, e você ainda pode usar diretamente componentes de frameworks populares como React, Vue e Svelte.

Um blogueiro resumiu bem: desenvolver templates no Hugo não é tão prático. Há muitos templates de código aberto disponíveis, mas personalizá-los pode ser complicado. No Astro, por outro lado, ajustar e personalizar templates é fácil e segue completamente a lógica moderna do desenvolvimento frontend.

Comparação com outros frameworks

Preparei uma tabela simples para você entender rapidamente as diferenças:

Quais projetos são adequados para a migração

Nem todo projeto é adequado para migrar para o Astro. Primeiro, veja se o seu projeto se encaixa em alguma destas categorias:

Projetos adequados para a migração:

• blogs pessoais e blogs técnicos;
• sites de documentação e bases de conhecimento;
• sites institucionais e páginas de apresentação de produtos;
• portfólios.

Projetos menos adequados para a migração:

• aplicações de página única altamente interativas, como dashboards e painéis administrativos;
• aplicações com dados atualizados em tempo real;
• aplicações que exigem muito gerenciamento de estado no cliente.

Em resumo, se o conteúdo é o centro do seu site, o Astro foi feito para você. Se o site precisa de muita interação e atualização em tempo real, talvez seja melhor continuar com Next.js ou outro framework SPA.

Preparação antes da migração

Não comece imediatamente. Preparar estes itens primeiro deixará todo o processo muito mais tranquilo.

1. Faça backup do projeto atual

Esta é a etapa mais importante. Recomendo usar uma branch do git:

# Criar uma branch para a migração
git checkout -b migrate-to-astro

# Garantir que o trabalho atual esteja salvo
git add .
git commit -m "Backup: início da migração para o Astro"

Assim, se algo der errado durante a migração, você poderá voltar para a branch original a qualquer momento.

2. Avalie o volume de trabalho

Antes de começar, avalie o volume de trabalho para saber o que esperar:

Avaliação do conteúdo:

• Número de artigos: ____
• Sintaxe Markdown utilizada: padrão/estendida
• Número de imagens: ____
• Local das imagens: caminho relativo/caminho absoluto

Estimativa de tempo:

• Menos de 50 artigos: 1 dia
• De 50 a 200 artigos: 2 dias
• Mais de 200 artigos: 3 dias

3. Escolha um tema para Astro

O Astro oferece muitos temas de blog excelentes. Escolher um visualmente próximo ao seu blog atual pode economizar bastante trabalho:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Temas recomendados:

• AstroPaper: tema de blog minimalista, adequado para blogs técnicos;
• Fuwari: oferece suporte a vários idiomas e muitos recursos;
• Astro Cactus: inclui um componente completo de árvore de navegação.

Crie o projeto rapidamente:

# Usar o tema AstroPaper
npm create astro@latest my-blog -- --template satnaing/astro-paper

# Ou usar o tema Fuwari
npm create astro@latest my-blog -- --template saicaca/fuwari

4. Prepare o ambiente

Confira se o seu ambiente de desenvolvimento atende aos requisitos:

• Node.js: v18.14.1 ou superior;
• Gerenciador de pacotes: npm, pnpm ou yarn;
• Extensão do VS Code: Astro, a extensão oficial e indispensável.

Etapas detalhadas para migrar do Hugo

Como o Hugo provavelmente tem a maior base de usuários, começarei por ele. Em termos gerais, a migração do Hugo para o Astro tem dificuldade moderada, e o principal trabalho é converter os templates.

Etapa 1: crie um projeto Astro

npm create astro@latest my-new-blog
cd my-new-blog
npm install

# Instalar integrações comuns
npx astro add mdx sitemap

Etapa 2: migre o conteúdo em Markdown

Esta é a etapa mais importante. A boa notícia é que a maior parte do frontmatter do Hugo e do Astro é compatível; você só precisa ajustar alguns campos.

Mapeamento dos campos do frontmatter:

# Formato do Hugo
---
title: "Meu artigo"
date: 2023-01-15
tags: ["Frontend", "Astro"]
---

# Formato do Astro (alteração indicada por ⬅)
---
title: "Meu artigo"
pubDate: 2023-01-15  ⬅ date passa a ser pubDate
tags: ["Frontend", "Astro"]
---

Se houver muitos artigos, você pode substituir o campo em lote com um script:

# macOS/Linux
find content -name "*.md" -exec sed -i '' 's/^date:/pubDate:/g' {} +

# Windows (PowerShell)
Get-ChildItem content -Filter *.md -Recurse | ForEach-Object {
    (Get-Content $_.FullName) -replace '^date:', 'pubDate:' | Set-Content $_.FullName
}

Etapa 3: converta os templates

Os templates do Hugo usam a sintaxe Go Template, enquanto o Astro usa uma sintaxe parecida com JSX. Mas há um atalho: se você tinha templates em HTML, pode colar o HTML diretamente em um arquivo .astro e concluir cerca de 70% do trabalho.

Exemplo de template do Hugo:

{{ range .Pages }}
  <article>
    <h2>{{ .Title }}</h2>
    <p>{{ .Summary }}</p>
  </article>
{{ end }}

Conversão para Astro:

---
const posts = await Astro.glob('../pages/blog/*.md');
---

{posts.map(post => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
  </article>
))}

A sintaxe não parece muito mais moderna?

Etapa 4: trate imagens e arquivos estáticos

Copie o conteúdo do diretório static/ do Hugo para o diretório public/ do Astro, mantendo os mesmos caminhos:

cp -r hugo-blog/static/* astro-blog/public/

As referências às imagens nos artigos não precisam ser alteradas se usam caminhos relativos ou absolutos, como /images/pic.jpg, pois o conteúdo do diretório public/ é mapeado diretamente para a raiz do site.

Etapa 5: configure os redirecionamentos de URL

Esta etapa é essencial para o SEO. Se a estrutura das URLs mudou, configure redirecionamentos 301.

No arquivo astro.config.mjs:

export default defineConfig({
  redirects: {
    '/old-path': '/new-path',
    '/posts/[slug]': '/blog/[slug]',
  }
})

Etapas detalhadas para migrar do Hexo

A migração do Hexo é parecida com a do Hugo, mas há alguns detalhes específicos que merecem atenção.

Etapa 1: crie o projeto e configure as Content Collections

pnpm create astro@latest my-blog --template satnaing/astro-paper
cd my-blog
pnpm install

O Astro usa Content Collections para gerenciar conteúdo. Você precisa configurá-las em src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
    tags: z.array(z.string()),
  }),
});

export const collections = { blog };

Essa configuração verifica os tipos do frontmatter e mostra um erro quando os campos não correspondem ao schema, o que é bastante útil.

Etapa 2: migre conteúdo e imagens

Copie os artigos do diretório source/_posts/ do Hexo para src/content/blog/ do Astro e substitua o campo date por pubDate em lote:

find src/content/blog -name "*.md" -exec sed -i 's/^date:/pubDate:/g' {} +

Há duas opções para tratar as imagens:

Opção 1: colocar no diretório public/ (simples e recomendada)

cp -r hexo-blog/source/images astro-blog/public/images

Os caminhos das imagens nos artigos não precisam ser alterados.

Opção 2: usar o componente Image do Astro (melhor desempenho)

---
import { Image } from 'astro:assets';
import myImage from '../assets/pic.jpg';
---

<Image src={myImage} alt="Descrição" />

Etapa 3: redirecione os caminhos das URLs

Por padrão, o Hexo usa o caminho /YYYY/MM/DD/post-name/, enquanto o Astro usa /blog/post-name/.

Se quiser manter o formato anterior, configure o redirecionamento em astro.config.ts:

export default defineConfig({
  redirects: {
    '/:year/:month/:day/:slug': '/blog/:slug',
  }
})

Etapa 4: configure o conteúdo completo no RSS

O Hexo inclui o conteúdo completo no RSS por padrão. No Astro, isso precisa ser configurado manualmente.

npx astro add rss

Configure o arquivo src/pages/rss.xml.js:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
import { marked } from 'marked';

export async function GET(context) {
  const posts = await getCollection('blog');

  return rss({
    title: 'Meu blog',
    description: 'Descrição do blog',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      link: `/blog/${post.slug}/`,
      content: marked.parse(post.body), // Incluir o conteúdo completo
    })),
  });
}

Etapas detalhadas para migrar do Next.js

A migração do Next.js para o Astro é um pouco mais complexa por causa das diferenças de arquitetura. No entanto, se você usa o Next.js no modo SSG, o trabalho será bem menor.

Etapa 1: entenda as diferenças de arquitetura

Principais diferenças:

• o Next.js é uma aplicação de página única (SPA) com um _app.js global;
• o Astro é um site de várias páginas (MPA), e cada página é independente.

Semelhanças:

• ambos oferecem suporte à sintaxe JSX;
• ambos usam roteamento baseado no sistema de arquivos;
• ambos oferecem suporte a SSG e SSR.

Prepare-se para uma mudança de perspectiva: você não está simplesmente “migrando” uma aplicação Next.js, mas “reconstruindo” um site de conteúdo com Astro.

Etapa 2: crie o projeto e instale a integração React

npm create astro@latest my-blog
cd my-blog
npx astro add react

Depois de instalar a integração React, você pode continuar usando seus componentes React existentes.

Etapa 3: defina a estratégia de migração dos componentes

O Astro aceita diretamente arquivos .jsx e .tsx, por isso seus componentes React podem ser copiados sem alterações.

Componente Next.js (sem alterações):

// components/Button.jsx
export default function Button({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>
}

Uso no Astro:

---
import Button from '../components/Button.jsx';
---

<Button client:load>Clique em mim</Button>

Observe a diretiva client:load: ela informa ao Astro que esse componente precisa de JavaScript. Por padrão, os componentes são estáticos.

Etapa 4: converta componentes React em componentes Astro

Para componentes sem interação, recomendo a conversão para componentes Astro, pois o desempenho será melhor.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Componente Next.js/React:

export default function Card({ title, description }) {
  const formattedDate = new Date().toLocaleDateString();

  return (
    <div className="card">
      <h2>{title}</h2>
      <p>{description}</p>
      <span>{formattedDate}</span>
    </div>
  );
}

Componente Astro:

---
const { title, description } = Astro.props;
const formattedDate = new Date().toLocaleDateString();
---

<div class="card">
  <h2>{title}</h2>
  <p>{description}</p>
  <span>{formattedDate}</span>
</div>

Principais diferenças:

• className → class;
• as props são obtidas por Astro.props;
• o código JavaScript fica entre os delimitadores ---.

Etapa 5: ajuste a estratégia de hydration

Por padrão, o Next.js aplica hydration a todos os componentes, carregando JavaScript para torná-los interativos. O Astro não faz isso por padrão.

Você precisa indicar manualmente quais componentes exigem interação:

Diretivas de hydration:

• client:load - faz hydration assim que a página é carregada;
• client:idle - faz hydration quando a página fica ociosa;
• client:visible - faz hydration quando o componente entra na área visível;
• client:only - renderiza apenas no cliente.

---
import Counter from '../components/Counter.jsx';
import HeavyChart from '../components/HeavyChart.jsx';
---

<!-- Interação imediata -->
<Counter client:load />

<!-- Carregamento adiado para melhorar o desempenho -->
<HeavyChart client:visible />

Essa estratégia é muito importante. Quando bem aplicada, pode melhorar bastante o desempenho.

Etapa 6: trate as rotas dinâmicas

O getStaticPaths do Next.js tem uma implementação equivalente no Astro, com uma sintaxe quase idêntica:

Rota dinâmica no Astro:

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Etapa 7: compare os resultados da otimização de desempenho

Este é o maior benefício da migração. Segundo relatos reais de desenvolvedores:

Antes da migração (Next.js SSG):

• PageSpeed Insights: 85 pontos;
• JavaScript no primeiro carregamento: ~200 KB;
• Lighthouse Performance: 80 a 90 pontos.

Depois da migração (Astro):

• PageSpeed Insights: 100 pontos em todos os testes;
• JavaScript no primeiro carregamento: ~10 KB, ou 0 KB se não houver componentes interativos;
• Lighthouse Performance: 95 a 100 pontos.

Os ganhos de desempenho vêm principalmente de:

• remoção do custo de hydration do React;
• CSS inline, reduzindo as requisições de rede;
• carregamento de JavaScript sob demanda.

Boas práticas gerais de migração

Independentemente do framework de origem, estas boas práticas são válidas.

1. Estratégia de migração em etapas

Você não precisa migrar todo o conteúdo de uma só vez. É possível avançar gradualmente:

Etapa 1: migração piloto

• escolha de 5 a 10 artigos para fazer um teste;
• valide se o processo de migração funciona bem;
• teste os ganhos de desempenho.

Etapa 2: migração completa

• migre todo o conteúdo dos artigos;
• converta todos os templates e componentes;
• configure as regras de redirecionamento.

Etapa 3: ajustes e otimizações

• adicione os recursos que estiverem faltando;
• otimize o desempenho;
• verifique o SEO.

Um blogueiro contou que começou escrevendo apenas alguns artigos novos com Astro e manteve os antigos como estavam. Essa abordagem gradual reduz os riscos.

2. Medidas de proteção do SEO

Um dos maiores receios da migração é prejudicar o SEO. Por isso, estes cuidados são indispensáveis:

Configure redirecionamentos 301

Se a estrutura das URLs mudou, configure redirecionamentos 301:

// Vercel: vercel.json
{
  "redirects": [
    { "source": "/old-path/:slug", "destination": "/new-path/:slug", "permanent": true }
  ]
}

// Cloudflare Pages: _redirects
/old-path/:splat /new-path/:splat 301

Atualize o sitemap

npx astro add sitemap

Configure em astro.config.mjs:

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://yourdomain.com',
  integrations: [sitemap()],
});

Envie para os mecanismos de busca

Depois de concluir a migração, envie o novo sitemap pelo Google Search Console e pelo Bing Webmaster Tools.

3. Otimize as imagens

O Astro oferece um componente específico para otimização de imagens. Vale a pena usá-lo:

npx astro add image

Exemplo de uso:

---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---

<Image src={cover} alt="Imagem de capa" width={800} height={600} />

Benefícios: geração automática de vários tamanhos, conversão automática para WebP e carregamento adiado.

4. Checklist de testes

Depois de concluir a migração, não publique imediatamente. Verifique primeiro estes itens:

Conteúdo:

• Todos os artigos são exibidos corretamente
• Os campos do frontmatter estão completos
• Os links nos artigos funcionam
• As páginas de tags e categorias funcionam

Recursos:

• Todas as imagens carregam corretamente
• Os estilos CSS são aplicados corretamente

Funcionalidades:

• A busca funciona
• O sistema de comentários funciona
• O feed RSS está disponível

SEO:

• O sitemap é gerado corretamente
• O robots.txt está correto
• As URLs antigas são redirecionadas corretamente

Desempenho:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

• Teste no PageSpeed Insights
• Verificação com o Lighthouse

Ferramentas recomendadas:

• Broken Link Checker - verifica links quebrados;
• PageSpeed Insights - testa o desempenho;
• Screaming Frog - rastreador de SEO.

Problemas comuns e soluções

Durante a migração, você pode encontrar alguns destes problemas. Aqui estão as soluções.

1. Diagnóstico de erros de build

Problema: Could not find Sharp

Esse erro indica um problema com uma dependência da otimização de imagens do Astro.

# Solução
npm install sharp

Se ainda não funcionar, desative a otimização de imagens em astro.config.mjs:

export default defineConfig({
  image: {
    service: { entrypoint: 'astro/assets/services/noop' }
  }
})

Problema: versão incompatível do MDX

Se você usa o Astro 5.0, precisa atualizar @astrojs/mdx para a versão 4.0.0:

npm install @astrojs/mdx@latest

2. Estilos ausentes

Problema: estilos não funcionam por causa do escopo do CSS

Por padrão, a tag <style> do Astro usa estilos com escopo, aplicados somente ao componente atual.

<!-- Estilos locais -->
<style>
  .card { color: blue; }
</style>

<!-- Estilos globais -->
<style is:global>
  .card { color: blue; }
</style>

Problema: os estilos do conteúdo Markdown desapareceram

O HTML renderizado a partir do Markdown precisa de estilos globais:

<style is:global>
  .prose h1 { font-size: 2rem; }
  .prose h2 { font-size: 1.5rem; }
  .prose p { margin: 1rem 0; }
  .prose code { background: #f4f4f4; padding: 0.2rem 0.4rem; }
</style>

<article class="prose">
  <Content />
</article>

Outra opção é usar diretamente o plugin Tailwind Typography.

3. Integração de serviços de terceiros

Sistema de comentários

O Astro oferece suporte à maioria dos sistemas de comentários, como Disqus, Giscus e Utterances:

<script
  src="https://giscus.app/client.js"
  data-repo="your-username/your-repo"
  data-repo-id="your-repo-id"
  data-category="Announcements"
  data-category-id="your-category-id"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="light"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async>
</script>

Ferramentas de análise

O Google Analytics pode ser usado diretamente:

<html>
  <head>
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>
  </head>
</html>

4. Configuração de implantação

Implantação no Vercel

Conecte diretamente o repositório do GitHub, e o Vercel reconhecerá automaticamente o projeto Astro.

Implantação no Cloudflare Pages

Configuração de build:

• Build command: npm run build
• Build output directory: dist
• Node.js version: 18 ou superior

Implantação no GitHub Pages

Configure em astro.config.mjs:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name',
})

Conclusão

Depois de tudo isso, migrar para o Astro não parece tão assustador. Segundo os relatos de desenvolvedores que reuni, a maioria consegue concluir a migração em 1 a 3 dias e fica satisfeita com o resultado.

Resumo dos pontos principais:

1. Faça backup: crie uma branch no git para poder reverter a qualquer momento
2. Migre gradualmente: teste primeiro com alguns artigos e só depois migre tudo
3. Proteja o SEO: configure redirecionamentos 301, atualize o sitemap e preserve o posicionamento nas buscas
4. Teste bem: antes de publicar, verifique se links, imagens e funcionalidades estão corretos
5. Aproveite os ganhos: a melhoria de desempenho após a migração é concreta, e chegar a 100 pontos no PageSpeed Insights fica muito mais fácil

Minha sugestão: se você ainda está em dúvida, crie uma branch de teste. Migre alguns artigos e faça testes de desempenho. Se gostar do resultado, migre todo o conteúdo; se não gostar, você não terá perdido nada.

Por fim, alguns recursos úteis:

• Documentação oficial do Astro
• Comunidade do Astro no Discord
• Biblioteca de temas do Astro

Boa migração! Se encontrar algum problema, compartilhe-o nos comentários.