Como migrar URLs de documentação Web3 sem perder buscas

Uma migração de documentação é mais segura quando cada URL antiga tem um destino definido deliberadamente e cada rota importante é verificada após o lançamento. Planejo a mudança como uma alteração no nível da URL, não como uma tarefa de redesign. Isso mantém a intenção da página, os redirecionamentos, o acesso dos rastreadores e os links internos visíveis em um único registro. Equipes de protocolos frequentemente movem a documentação entre subdomínios, frameworks ou sistemas de hospedagem. O risco para as buscas surge quando se perde o caminho entre um endereço antigo e sua substituição útil. Este guia apresenta uma sequência prática para mapear esse caminho, testá-lo e monitorar o que continua incerto.

Mapeie as URLs antes de escolher uma nova estrutura

Comece com uma lista completa das URLs que podem importar para o leitor: guias, referências de API, notas de versão, páginas de glossário, tutoriais e páginas vinculadas às interfaces do produto. Exporte o sitemap atual, rastreie o host da documentação e compare as duas listas. Um sitemap mostra URLs declaradas. Um rastreamento mostra links acessíveis. Nenhum dos dois prova que todas as URLs históricas foram capturadas; por isso, adicione páginas de destino do Search Console, páginas de destino do Analytics e links de suporte quando tiver acesso a eles. Registre a data de coleta e a fonte de cada lista.

Para cada URL antiga, registre a finalidade da página, a tarefa do público, o último status conhecido e o destino proposto. Faça o mapeamento por intenção. Uma migração de /developers/v1/bridge deve apontar para o guia atual da bridge se essa página responder à mesma tarefa. A página inicial genérica da documentação não é uma substituição equivalente para uma referência específica de API. Se o conteúdo não tiver sucessor, registre essa decisão e determine se a página antiga deve permanecer, ser retirada ou redirecionar para uma página-pai realmente útil. Não encaminhe todas as páginas removidas para a nova página inicial. Isso cria um caminho ruim para o leitor e pode ocultar qual conteúdo foi de fato preservado.

Use uma tabela de mapeamento com uma linha por endereço antigo. Inclua o caminho de origem exato, o destino final, o motivo do mapeamento, o responsável e o resultado do teste. Normalize barras finais e maiúsculas ou minúsculas apenas de acordo com o comportamento do servidor de origem. Mantenha os parâmetros de consulta quando carregarem um estado relevante do usuário. Trate explicitamente os caminhos de idioma e versão. O mapa de URLs se torna a lista de aceitação da migração; portanto, as linhas ambíguas devem ser resolvidas antes da troca de DNS ou hospedagem.

Configure redirecionamentos permanentes e preserve o acesso dos rastreadores

Quando uma página foi movida permanentemente, o Google Search Central recomenda redirecionamentos permanentes no lado do servidor. Implemente um único redirecionamento direto da URL antiga para seu destino final. Evite cadeias como URL antiga para um host intermediário e depois para uma URL nova. As cadeias adicionam pontos de falha e tornam a experiência final do leitor mais difícil de testar. O redirecionamento deve preservar o caminho relevante e, quando necessário, a string de consulta. Teste URLs representativas e o arquivo completo de mapeamento após a implantação, não apenas o domínio raiz.

Um redirecionamento não ajuda um rastreador se o host antigo já não responder. Mantenha o domínio antigo, o certificado TLS e a configuração de redirecionamento ativos durante o período planejado para a migração. Revise os redirecionamentos na camada de atendimento que realmente recebe as solicitações. Uma regra no framework não ajuda se o proxy de borda interceptar a solicitação primeiro. Confirme o código de resposta, o destino de Location e a resposta da página final de fora do ambiente de build.

Verifique o robots.txt separadamente. O Google descreve esse arquivo como uma forma de controlar o acesso dos rastreadores às URLs, não como uma maneira confiável de manter uma página fora do Google. Uma diretiva ampla de bloqueio pode impedir o Google de buscar a página e identificar um noindex no nível da página. Revise as regras nos hosts antigo e novo. Confirme também que os recursos da documentação necessários para renderizar o conteúdo estão acessíveis. As regras de robots são específicas de cada host; portanto, um arquivo correto no domínio de marketing não estabelece acesso em um subdomínio de documentação.

Valide canônicas, links e respostas das páginas

Uma lista de verificação de migração deve validar mais do que redirecionamentos. No novo destino, confirme que a página retorna uma resposta bem-sucedida, renderiza seu texto principal sem exigir uma rota do lado do cliente que não esteja disponível e declara a URL canônica pretendida. A canônica deve apontar para o novo endereço preferencial, não para a URL aposentada ou para uma página inicial sem relação. Verifique as referências a idiomas alternativos quando a documentação estiver localizada. Um seletor de idioma deve levar ao tópico correspondente quando ele existir, em vez de enviar todos os idiomas para a raiz.

Atualize os links que sua equipe controla. Substitua links internos na navegação do produto, nos portais de desenvolvedores, nos tutoriais, nos exemplos de API, nas notas de versão e nos macros de suporte. Os redirecionamentos ajudam as pessoas que usam favoritos antigos, mas não substituem os links atuais. O Search Central recomenda atualizar os links internos para apontarem diretamente para as novas URLs durante uma mudança. Isso também reduz a dependência da camada de redirecionamento.

Use uma amostra que inclua páginas de alto valor, caminhos profundos, strings de consulta, páginas com barras finais, conteúdo retirado e cada idioma. Em seguida, execute a lista de mapeamento em lote. Salve o resultado com registro de data e hora, método da solicitação, status da resposta, URL final e qualquer divergência. Uma URL que retorna uma página de erro suave com HTTP 200 precisa de inspeção humana. O status, por si só, não prova que o conteúdo pretendido foi carregado.

Monitore a mudança e responda às lacunas

Após o lançamento, inspecione os logs do servidor e o Search Console em busca de caminhos antigos que ainda recebem solicitações, páginas novas que não conseguem ser rastreadas, 404 inesperados e páginas que o Google selecionou de forma diferente da canônica declarada. Compare grupos de páginas equivalentes ao longo do tempo. Diferencie um atraso temporário no novo rastreamento de um destino quebrado verificando a resposta real e o conteúdo renderizado. Os relatórios de busca não são uma certificação instantânea de uma migração, e nenhuma lista de verificação pode garantir a continuidade do posicionamento.

Mantenha um registro curto de problemas. Para cada anomalia, capture a URL antiga, o destino esperado, a resposta observada, o primeiro horário de observação, as evidências e o responsável. Corrija o redirecionamento ou o destino, teste novamente e encerre o registro com um resultado atualizado. Se o destino realmente desapareceu, escolha uma substituição útil apenas quando existir uma. Caso contrário, deixe a URL retornar uma resposta honesta de não encontrado e remova os links que indiquem que o conteúdo ainda está disponível.

Para uma revisão técnica mais ampla, compare este processo de migração com o [guia de SEO técnico para Web3](guia de SEO técnico para Web3) e a [referência de SEO para Web3](referência de SEO para Web3). O objetivo não é prometer um resultado de busca. É preservar um caminho claro para leitores e rastreadores e, então, tornar qualquer perda restante visível o suficiente para ser diagnosticada.

O Google diferencia redirecionamentos permanentes e temporários pelo sinal que eles fornecem sobre o destino canônico. Sua documentação lista HTTP 301 e 308 como opções permanentes no lado do servidor, e HTTP 302, 303 e 307 como opções temporárias. Essa contagem descreve apenas as opções documentadas de códigos de status. Ela não mede efeitos sobre o posicionamento nem estabelece qual regra se adequa a uma migração específica. Escolha com base no fato de a mudança ser realmente permanente e, em seguida, teste a resposta implantada e o destino.

Registro de evidências

Perguntas frequentes

Como os redirecionamentos afetam a Pesquisa Google?

Um redirecionamento informa aos visitantes e rastreadores que uma URL resolve em outro lugar. Para uma mudança permanente, o Google recomenda um redirecionamento permanente no lado do servidor. Isso não garante que o posicionamento ou o tráfego permaneçam inalterados.

Toda URL antiga da documentação deve redirecionar para a nova página inicial?

Não. Mapeie uma página antiga para a página mais próxima que atenda à mesma tarefa. Se não existir uma equivalente, registre essa decisão e use uma resposta honesta de retirada em vez de uma solução genérica enganosa.

O robots.txt remove uma página do Google?

Não. O Google afirma que o robots.txt controla o acesso dos rastreadores e não é um mecanismo para manter uma página fora do Google. Use os controles de indexação documentados que se encaixarem no caso e certifique-se de que os rastreadores possam buscar os sinais necessários.

O que devo verificar após uma migração da documentação?

Teste cada URL mapeada, a resposta final, a canônica, os links internos e o acesso dos rastreadores. Depois, monitore os logs e o Search Console em busca de caminhos quebrados ou de uma seleção canônica inesperada.

Referências

1. https://developers.google.com/search/docs/crawling-indexing/301-redirects, acessado em 2026-11-09.
2. https://developers.google.com/search/docs/crawling-indexing/robots/intro, acessado em 2026-11-09.