Como adicionar busca com Pagefind a um blog Astro: guia completo, gratuito, rápido e com suporte a chinês

Quanto mais artigos eu publicava no blog, mais mensagens recebia dos leitores: “Você poderia adicionar uma busca? Lembro que escreveu sobre determinado assunto, mas procurei por um tempão e não encontrei”.

Eu vinha adiando essa melhoria. O Algolia era caro demais — dezenas de dólares por mês não fazem sentido para um blog pessoal — e montar uma solução com Elasticsearch daria trabalho demais. Foi então que descobri o Pagefind: configuração simples, índice de apenas algumas dezenas de KB, totalmente gratuito e com suporte nativo a chinês.

O que é o Pagefind? Em poucas palavras, é um mecanismo de busca feito para sites estáticos. Ele gera o índice automaticamente durante o build, realiza todas as pesquisas no navegador e dispensa tanto um servidor de backend quanto APIs de terceiros. Melhor ainda: é gratuito, extremamente rápido e muito fácil de configurar.

Neste artigo, vou mostrar passo a passo:

• por que o Pagefind é mais adequado que o Algolia para blogs pessoais;
• como concluir a configuração em 10 minutos;
• como fazer ajustes avançados e otimizar a busca em chinês;
• como resolver os problemas mais comuns.

Se você criou um blog com Astro, quer adicionar busca e não pretende pagar por isso, este guia é para você.

Por que escolher o Pagefind?

Antes de decidir como adicionar busca ao blog, comparei as soluções mais conhecidas. Acabei escolhendo o Pagefind por três motivos principais: custo, privacidade e desempenho.

As vantagens específicas da busca estática

O Pagefind é uma solução de “busca estática”: o índice é gerado durante o build, publicado junto com o site e consultado diretamente no navegador. Essa abordagem traz benefícios claros.

É totalmente gratuito. Ao contrário do Algolia, que cobra conforme a quantidade de buscas, o Pagefind não tem custo. Mesmo que o tráfego do seu blog cresça muito, o recurso de busca continuará sem cobrar nada.

Respeita a privacidade. As pesquisas dos usuários não são enviadas a servidores de terceiros; todas as consultas acontecem localmente. Para leitores preocupados com privacidade, isso é especialmente importante.

Dispensa backend. Soluções de busca tradicionais exigem manutenção de servidor e banco de dados, além de cuidados com alta disponibilidade. O Pagefind é totalmente estático, fica no CDN e tem a mesma estabilidade das suas páginas.

Carrega sob demanda. O índice do Pagefind é dividido em pequenos blocos, e somente as partes necessárias são carregadas quando o usuário começa a pesquisar. Isso não afeta o carregamento inicial e oferece uma ótima experiência.

Comparação entre Pagefind e Algolia

Montei esta tabela para facilitar a comparação:

Para ser justo, o Algolia é realmente poderoso: velocidade de busca, tolerância a erros de digitação e recursos de análise estão entre os melhores do mercado. Para um blog pessoal, porém, é uma solução grande demais para o problema. Além disso, quando o tráfego do blog aumenta, os custos do Algolia podem subir rapidamente.

Casos reais e números

O desempenho do Pagefind é excelente. Segundo um teste do BryceWray.com, o índice de busca gerado para um site com 10 mil páginas ficou abaixo de 300 KB. Na maioria dos blogs, o índice fica em torno de 100 KB.

Os dados de teste publicados pelo próprio Pagefind são ainda mais impressionantes: o índice de um site com 19 páginas levou apenas 0,043 segundo. Como a ferramenta foi escrita em Rust, o build é muito rápido; mesmo blogs com milhares de páginas levam apenas alguns segundos.

Em aplicações reais, o Starlight, site de documentação oficial do Astro, já traz o Pagefind como solução de busca padrão. Se até o projeto oficial do Astro escolheu a ferramenta, é um bom sinal de que ela é confiável.

Configure o Pagefind em 5 etapas

Agora que a parte teórica terminou, vamos à prática. Vou acompanhar você em cada etapa da configuração do Pagefind, que realmente leva apenas 10 minutos.

Etapa 1: instale as dependências

Comece instalando estes dois pacotes npm:

npm install astro-pagefind pagefind

Talvez você esteja se perguntando por que são necessários dois pacotes.

astro-pagefind é a integração com o Astro e executa o Pagefind automaticamente durante o build. Já pagefind é a biblioteca principal, que inclui a interface e a API de busca. Precisamos das duas porque, mais adiante, vamos importar diretamente os recursos do pagefind.

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

Ver preços →Anúncio

Etapa 2: configure o astro.config.mjs

Abra o arquivo astro.config.mjs e adicione a integração do Pagefind:

import { defineConfig } from 'astro/config';
import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [pagefind()],
});

É só isso. Depois dessas linhas, sempre que você executar npm run build, o Pagefind indexará automaticamente o conteúdo do site.

Etapa 3: crie o componente de busca

Crie um componente Search.astro no diretório src/components/:

---
// src/components/Search.astro
---

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>

<script>
  window.addEventListener('DOMContentLoaded', () => {
    new PagefindUI({
      element: "#search",
      showSubResults: true,
      showImages: false
    });
  });
</script>

Há algumas opções importantes aqui:

• element: define o elemento DOM em que a interface será montada;
• showSubResults: exibe resultados secundários, como os parágrafos encontrados;
• showImages: define se as miniaturas das páginas devem aparecer — normalmente desativo essa opção para carregar mais rápido.

Se o seu site usa ViewTransitions, adicione a diretiva transition:persist para evitar que o componente de busca seja inicializado novamente durante a navegação:

<div id="search" transition:persist></div>

Etapa 4: use o componente em uma página

Há duas maneiras de usar o componente de busca.

Opção 1: incluí-lo na barra de navegação

Importe o componente diretamente no Header.astro ou no Navbar.astro:

---
import Search from '../components/Search.astro';
---

<header>
  <nav>
    <!-- Seus links de navegação -->
  </nav>
  <Search />
</header>

Opção 2: criar uma página de busca separada

Crie o arquivo src/pages/search.astro:

---
import Layout from '../layouts/Layout.astro';
import Search from '../components/Search.astro';
---

<Layout title="Busca">
  <main>
    <h1>Buscar artigos</h1>
    <Search />
  </main>
</Layout>

Depois, adicione à barra de navegação um link para /search. Pessoalmente, prefiro essa abordagem porque ela evita deixar a navegação muito cheia.

Etapa 5: gere e teste

Configuração concluída. Agora execute o comando de build:

npm run build

Se tudo estiver correto, você verá uma saída parecida com esta:

Running Pagefind...
Indexed 42 pages
Indexed 3,582 words
Created 5 index chunks
Finished in 0.234 seconds

Para testar localmente, execute:

npm run build && npx pagefind --site dist --serve

Abra http://localhost:1234 no navegador e experimente o recurso de busca.

Se o campo aparecer e uma palavra-chave retornar resultados, parabéns: a configuração deu certo.

Configurações e otimizações avançadas

Com a configuração básica, a busca já funciona. Mas, para torná-la mais precisa, rápida e adequada às suas necessidades, você pode aplicar alguns ajustes avançados.

Controle precisamente o conteúdo indexado

Por padrão, o Pagefind indexa tudo dentro da tag <body>. Isso significa que textos da barra de navegação, da lateral e do rodapé também entram no índice e podem prejudicar a qualidade dos resultados.

Imagine que o rodapé contenha uma apresentação “Sobre mim”. Ao pesquisar por “autor”, o usuário encontraria todas as páginas, pois o mesmo rodapé aparece em cada uma delas.

A solução é usar o atributo data-pagefind-body para definir a área que deve ser indexada:

<body>
  <nav data-pagefind-ignore>
    <!-- A barra de navegação não será indexada -->
  </nav>

  <main data-pagefind-body>
    <!-- Somente o conteúdo principal será indexado -->
    <article>
      <h1>Título do artigo</h1>
      <p>Conteúdo do artigo...</p>
    </article>
  </main>

  <aside data-pagefind-ignore>
    <!-- A barra lateral não será indexada -->
  </aside>

  <footer data-pagefind-ignore>
    <!-- O rodapé não será indexado -->
  </footer>
</body>

Depois que você usa data-pagefind-body, o Pagefind indexa somente o conteúdo dentro desse elemento e ignora automaticamente as demais áreas. Para excluir apenas alguns elementos, use data-pagefind-ignore.

Essa configuração oferece duas vantagens:

1. Busca mais precisa — somente o conteúdo principal entra na pesquisa, sem interferência de textos irrelevantes.
2. Índice menor — ao remover barras de navegação e rodapés repetidos, o índice diminui entre 30% e 50%.

Personalize metadados e títulos

Por padrão, o Pagefind usa o primeiro <h1> da página como título do resultado e os primeiros parágrafos como resumo. Em alguns casos, isso não é suficientemente preciso.

Você pode definir esses dados manualmente com data-pagefind-meta:

<!-- Substitui o título padrão -->
<h1 data-pagefind-meta="title">Guia para implementar busca no Astro</h1>

<!-- Define o resumo -->
<p data-pagefind-meta="description">
  Este artigo mostra como adicionar busca com Pagefind a um blog Astro, com todas as etapas de configuração e otimizações para chinês.
</p>

<!-- Define a imagem -->
<img data-pagefind-meta="image[src]" src="/cover.jpg" alt="Capa">

Ajuste o peso dos resultados

Se você quer que correspondências no título apareçam primeiro, ajuste o peso dos elementos:

<h1 data-pagefind-weight="10.0">Título do artigo</h1>
<p data-pagefind-weight="1.0">Conteúdo do artigo</p>

Quanto maior o peso, melhor será a posição dos resultados que correspondem àquele elemento. O valor padrão é 1.0; para títulos, geralmente se usa entre 5.0 e 10.0.

Teste prático da busca em chinês

Talvez você esteja preocupado: como o Pagefind é uma ferramenta estrangeira, será que funciona bem com chinês?

A boa notícia é que o Pagefind oferece suporte multilíngue nativo, incluindo chinês, e funciona sem nenhuma configuração adicional. Nos testes, o resultado foi bom:

• Segmentação precisa: ao buscar “Astro搜索”, encontra “Astro”, “搜索” e “Astro搜索功能”.
• Correspondência aproximada: ao buscar “博客搜索”, encontra “给博客加搜索” e “博客的搜索功能”.
• Sem suporte a pinyin: essa é a única limitação; buscar “boke” não encontra “博客”, embora isso tenha pouco impacto em um blog técnico.

Personalize a interface de busca

A interface padrão do Pagefind já atende à maioria dos casos. Para uma personalização mais profunda, como mudar o visual ou adicionar filtros, você pode usar a API JavaScript:

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

Começar →Anúncio

// Inicializa o Pagefind
const pagefind = await import("/pagefind/pagefind.js");

// Executa a busca
const search = await pagefind.search("Astro");

// Obtém os detalhes dos resultados
const results = await Promise.all(
  search.results.map(r => r.data())
);

// Renderiza uma interface personalizada
results.forEach(result => {
  console.log(result.url);      // URL da página
  console.log(result.meta.title); // Título
  console.log(result.excerpt);   // Resumo
});

Usar a API permite controlar totalmente a interface e integrá-la ao seu design system. A desvantagem é precisar escrever a lógica de renderização; para a maioria das pessoas, a interface padrão já é suficiente.

Problemas comuns e soluções

Durante a configuração, você pode encontrar alguns pequenos problemas. Veja os casos mais comuns e como resolvê-los.

Problema 1: título ou resumo incorreto nos resultados

Sintoma: o título exibido no resultado não é o título do artigo, ou o resumo contém o texto da barra de navegação.

Causa: por padrão, o Pagefind seleciona o primeiro <h1> e os primeiros parágrafos. Se a estrutura da página não seguir esse padrão, ele pode escolher o conteúdo errado.

Solução: defina os dados manualmente com data-pagefind-meta:

---
// Arquivo de layout BlogPost.astro
const { title, description } = Astro.props;
---

<article>
  <h1 data-pagefind-meta="title">{title}</h1>
  <p data-pagefind-meta="description">{description}</p>
  <!-- Outros conteúdos -->
</article>

Problema 2: a busca para de funcionar com ViewTransitions

Sintoma: depois de ativar o Astro ViewTransitions, o campo de busca não funciona ao navegar para a página de pesquisa.

Causa: o ViewTransitions executa o script novamente, mas o DOM já foi limpo, o que faz a inicialização falhar.

Solução: adicione a diretiva transition:persist ao contêiner da busca:

<div id="search" transition:persist></div>

Isso orienta o Astro a preservar o elemento durante a navegação, sem renderizá-lo novamente.

Problema 3: comando pagefind não encontrado durante o build

Sintoma: ao executar npm run build, aparece o erro pagefind: command not found.

Causa: somente o pacote astro-pagefind foi instalado, sem o pacote principal pagefind.

Solução: instale os dois pacotes:

npm install astro-pagefind pagefind

Se o problema continuar, confirme que a integração foi adicionada corretamente ao astro.config.mjs.

Problema 4: erro 404 após a implantação

Sintoma: tudo funciona no teste local, mas, depois da implantação no Cloudflare Pages ou Netlify, o navegador retorna 404 ao pesquisar e não encontra /pagefind/pagefind.js.

Causa: a pasta pagefind não está no resultado do build, possivelmente por uma configuração incorreta do comando.

Solução: confirme que o comando de build inclui a etapa de geração do índice. Se você usa a integração astro-pagefind, isso deve acontecer automaticamente. Caso não aconteça, altere manualmente o package.json:

{
  "scripts": {
    "build": "astro build && npx pagefind --site dist"
  }
}

Na implantação, garanta que esse comando de build seja usado.

Problema 5: erro de CSP ou índice muito grande

Erro de CSP (Content Security Policy)

Se o console do navegador mostrar Refused to load WebAssembly, o motivo é que o Pagefind usa WebAssembly. Nesse caso, adicione a diretiva wasm-unsafe-eval ao cabeçalho CSP:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'

Se você usa o Cloudflare Pages, adicione isto ao arquivo _headers:

/*
  Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; default-src 'self'

Índice muito grande

Se a pasta pagefind ocupar vários MB depois do build, talvez você esteja indexando conteúdo desnecessário. A solução é limitar precisamente o escopo e indexar apenas o conteúdo principal:

<body>
  <nav data-pagefind-ignore>...</nav>
  <main data-pagefind-body>
    <!-- Somente esta área será indexada -->
  </main>
  <footer data-pagefind-ignore>...</footer>
</body>

Isso pode reduzir o índice entre 30% e 50%. Além disso, como o Pagefind carrega sob demanda, o usuário baixa apenas a parte do índice correspondente à palavra-chave pesquisada; o volume efetivamente transferido é pequeno.

Caso prático e boas práticas

Depois de concluir a configuração, algumas recomendações ajudam a tornar o recurso ainda melhor.

Monitore a qualidade do índice

A cada build, o Pagefind exibe estatísticas do índice. Observe estes indicadores:

Running Pagefind...
Indexed 42 pages       ← Quantidade de páginas indexadas
Indexed 3,582 words    ← Total de palavras
Created 5 index chunks ← Quantidade de blocos do índice
Finished in 0.234 seconds

Como interpretar os principais indicadores:

• pages deve corresponder à quantidade de artigos. Se o número for menor, algumas páginas não foram indexadas — verifique se não foram excluídas por data-pagefind-ignore.
• Quanto menos index chunks, melhor: isso indica um índice pequeno. Em geral, há um bloco para cada 1.000 a 2.000 páginas.
• Se o build levar mais de 5 segundos, o volume de conteúdo ou o escopo do índice pode ser grande demais; considere fazer ajustes.

Checklist de implantação

Antes de publicar em produção, confira estes itens:

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

Ganhar 15% off →Anúncio

1. Confirme que a pasta pagefind existe

ls dist/pagefind

Você deve encontrar arquivos como pagefind.js, pagefind-ui.js e pagefind-ui.css.

2. Teste o recurso de busca

• Pesquise palavras-chave comuns e confirme que há resultados.
• Pesquise termos em chinês e confirme que a segmentação funciona corretamente.
• Pesquise uma palavra inexistente e confirme que aparece a mensagem “Nenhum resultado”.

3. Verifique o tamanho do índice

du -sh dist/pagefind

Normalmente, o tamanho deve ficar entre 50 KB e 500 KB. Se ultrapassar 1 MB, considere reduzir o escopo do índice.

4. Teste em dispositivos móveis

Abra o site no celular e confirme que a busca funciona. A interface padrão do Pagefind é responsiva, mas interfaces personalizadas precisam ser adaptadas por você.

Considerações de SEO

A página de busca não precisa ser indexada pelos mecanismos de pesquisa. Recomendo adicionar noindex ao search.astro:

<head>
  <meta name="robots" content="noindex, follow">
</head>

Assim, os mecanismos de busca não indexam a página de pesquisa, mas ainda seguem os links nela presentes, caso haja artigos recomendados.

Recomendações de desempenho

1. Carregue o componente de busca sob demanda

Se o campo fica na barra de navegação, mas a maioria dos usuários não o utiliza, vale carregá-lo sob demanda:

<div id="search"></div>

<script>
  // Carrega o Pagefind somente quando o usuário clica no ícone de busca
  document.getElementById('search-icon').addEventListener('click', async () => {
    const pagefind = await import("/pagefind/pagefind-ui.js");
    new PagefindUI({ element: "#search" });
  });
</script>

Assim, os recursos do Pagefind não são carregados na primeira tela e o desempenho melhora.

2. Use cache no CDN

Os arquivos de índice do Pagefind são estáticos. Garanta que o CDN os armazene em cache:

# _headers (Cloudflare Pages)
/pagefind/*
  Cache-Control: public, max-age=31536000, immutable

3. Otimize com pré-carregamento

Se o usuário permanecer na página de busca, você pode pré-carregar os índices de palavras-chave frequentes:

const pagefind = await import("/pagefind/pagefind.js");

// Pré-carrega os índices de palavras-chave populares
pagefind.preload("Astro");
pagefind.preload("React");

Conclusão

Depois de tudo isso, a conclusão é simples: o Pagefind é a melhor opção para adicionar busca a um blog Astro. Ele é totalmente gratuito, fácil de configurar, tem ótimo desempenho e oferece suporte a chinês.

Em comparação com o custo anual de centenas de dólares do Algolia, o Pagefind gera uma grande economia. Além disso, dispensa a manutenção de servidores e a configuração de APIs: é realmente uma ferramenta que funciona logo após a instalação.

Se você ainda está em dúvida sobre adicionar busca ao blog, recomendo reservar 10 minutos para testar o Pagefind. A configuração é muito mais simples do que parece, e o resultado pode superar as suas expectativas.

Por fim, se você encontrar algum problema durante a configuração, deixe um comentário. E, se já configurou o Pagefind com sucesso, compartilhe também como foi a sua experiência.

Leitura complementar:

• Documentação oficial do Pagefind
• Guia de busca do Astro Starlight
• Repositório astro-pagefind no GitHub