Migrações TYPO3: Um Checklist Completo para Evitar Pesadelos

Passei por migrações de TYPO3 suficientes para saber que a diferença entre uma transição tranquila e um pesadelo de seis meses resume-se à preparação. TYPO3 é um CMS poderoso — existe desde 1998 e executa alguns sites empresariais verdadeiramente complexos, especialmente na região DACH. Mas quando é hora de migrar, seja você atualizando entre versões TYPO3 maiores ou movendo para uma plataforma completamente diferente, o processo pode ficar feio rapidamente se você não tiver um plano.

Este é o checklist que gostaria que alguém tivesse me entregado antes da minha primeira migração TYPO3. Não é teórico. Cada item aqui existe porque vi o que acontece quando você o pula.

Índice

• Avaliar Sua Instalação TYPO3 Atual
• Definir Sua Estratégia de Migração
• Auditoria de Conteúdo e Mapeamento de Dados
• Preparação da Infraestrutura Técnica
• Inventário de Extensões e Integrações
• Plano de Preservação de SEO
• A Fase de Execução da Migração
• Testes e Garantia de Qualidade
• Monitoramento Pós-Migração
• Armadilhas Comuns em Migrações TYPO3
• FAQ

Avaliar Sua Instalação TYPO3 Atual

Antes de tocar em qualquer coisa, você precisa entender exatamente com o que está trabalhando. Isso parece óbvio. Não é. Entrei em projetos onde a equipe nem sabia qual versão do TYPO3 estava rodando em produção.

Auditoria de Versão e Ambiente

Comece aqui:

# Verifique sua versão TYPO3
php typo3/sysext/core/bin/typo3 --version

# Ou verifique pelo backend: Help > About TYPO3

Documente o seguinte:

• Versão TYPO3 (maior e menor — ex: TYPO3 v11.5.38 LTS)
• Versão PHP rodando no servidor
• Tipo de banco de dados e versão (MySQL, MariaDB, PostgreSQL)
• Servidor web (Apache, Nginx)
• Instalação baseada em Composer ou clássica — isso importa enormemente
• Número de sites/domínios na instalação (configurações multi-site adicionam complexidade)
• Número total de páginas e elementos de conteúdo na árvore de páginas

Mapeamento de Usuários e Permissões

O sistema de permissões de usuários e grupos do backend do TYPO3 é notoriamente granular. Exporte suas tabelas be_users e be_groups e documente:

• Quantos usuários de backend existem
• Quais permissões customizadas estão configuradas
• Quais usuários têm acesso de administrador
• Qualquer sobreposição de TSconfig customizada

Se você está migrando para um CMS diferente, precisará mapear essas funções para o modelo de permissões do novo sistema. Se você está atualizando versões do TYPO3, algumas configurações de permissões podem precisar ser atualizadas.

Complexidade do TypoScript e Configuração

Execute uma auditoria rápida de sua configuração TypoScript:

# Conte seus arquivos TypoScript
find . -name '*.typoscript' -o -name '*.ts' | wc -l

# Verifique setup.txt e constants.txt (formato legado)
find . -name 'setup.txt' -o -name 'constants.txt' | wc -l

Se você tiver centenas de arquivos TypoScript com configurações profundamente aninhadas, espere que a migração demore mais. Vi instalações TYPO3 com 10.000+ linhas de TypoScript que evoluíram ao longo de 15 anos. Isso não é um projeto de fim de semana.

Definir Sua Estratégia de Migração

Existem fundamentalmente três tipos de migrações TYPO3, e você precisa decidir qual você está fazendo antes de qualquer outra coisa.

Tipo de Migração	Quando Escolher	Complexidade	Timeline Típico
Atualização de versão TYPO3 (ex: v10 → v12)	Você quer permanecer no TYPO3	Médio-Alto	4-12 semanas
TYPO3 para CMS headless (ex: Contentful, Strapi, Sanity)	Você quer flexibilidade moderna de frontend	Alto	8-20 semanas
TYPO3 para outro CMS tradicional (ex: WordPress, Drupal)	Você quer um CMS monolítico diferente	Médio	6-16 semanas
TYPO3 para TYPO3 headless (usando EXT:headless)	Você quer backend TYPO3 com frontend moderno	Médio	6-14 semanas

Atualizando Dentro do TYPO3

Se você está permanecendo no TYPO3, o caminho de atualização oficial exige passar por cada versão LTS. Você não pode pular de v8 para v12 diretamente. Bem, você pode tentar. Não faça.

O caminho recomendado até 2025:

• v8 LTS → v9 LTS → v10 LTS → v11 LTS → v12 LTS → v13 LTS

TYPO3 v13 LTS foi lançado no final de 2024 e é a versão de suporte de longo prazo atual. TYPO3 v12 LTS receberá atualizações de segurança até abril de 2026 através do programa Extended Long Term Support (ELTS).

Migrando Para Fora do TYPO3

Se você está se movendo para uma arquitetura headless — e honestamente, para muitas equipes isso faz muito sentido — você vai querer avaliar suas opções de framework de frontend. Fizemos trabalhos extensivos com Next.js e Astro como camadas de frontend emparelhadas com plataformas CMS headless.

A pergunta-chave é: seu modelo de conteúdo justifica a complexidade do TYPO3? Se você está rodando um site de marketing com 200 páginas, TYPO3 é provavelmente demais. Se você está rodando um portal empresarial multi-idioma complexo com fluxos de trabalho, o trabalho de modelagem de conteúdo durante a migração será significativo independentemente de para onde você está indo.

Auditoria de Conteúdo e Mapeamento de Dados

Isso é onde as migrações vivem ou morrem. Conteúdo.

Exportação e Análise de Banco de Dados

TYPO3 armazena conteúdo principalmente nestas tabelas:

• pages — estrutura da árvore de páginas
• tt_content — elementos de conteúdo
• sys_file e sys_file_reference — ativos de mídia (FAL)
• sys_category — categorias
• tx_news_domain_model_news — se você estiver usando a extensão de notícias

Exporte seu conteúdo e obtenha números reais:

-- Conte páginas por tipo
SELECT doktype, COUNT(*) as count 
FROM pages 
WHERE deleted = 0 
GROUP BY doktype;

-- Conte elementos de conteúdo por tipo
SELECT CType, COUNT(*) as count 
FROM tt_content 
WHERE deleted = 0 AND hidden = 0 
GROUP BY CType 
ORDER BY count DESC;

-- Conte referências de arquivo
SELECT COUNT(*) FROM sys_file WHERE missing = 0;

Mapeamento de Tipo de Conteúdo

Crie uma planilha mapeando cada tipo de conteúdo TYPO3 (CType) para seu equivalente no sistema de destino. Tipos de conteúdo TYPO3 comuns que você encontrará:

• text, textmedia, textpic — conteúdo de texto padrão
• image — galerias de imagens
• table — tabelas de dados
• bullets — listas
• uploads — listas de arquivos
• html — HTML bruto (estes são sempre divertidos durante a migração)
• list — conteúdo de plugin (aqui fica complicado)
• Tipos de conteúdo customizados de extensões

O list CType é o complicado. Representa conteúdo de plugin — listagens de notícias, formulários, funcionalidade customizada — e cada um precisa de atenção individual.

Conteúdo Multi-Idioma

TYPO3 lida com traduções através de modo conectado (onde traduções estão vinculadas a um registro de idioma padrão) ou modo livre. Verifique qual abordagem seu site usa:

-- Verifique configuração de tradução
SELECT sys_language_uid, COUNT(*) 
FROM pages 
WHERE deleted = 0 
GROUP BY sys_language_uid;

Se você tem 8 idiomas com traduções em modo conectado, seu mapeamento de dados de migração acabou de ficar 8x mais complexo. Planeje de acordo.

Preparação da Infraestrutura Técnica

Requisitos do Servidor

Se você estiver atualizando para TYPO3 v13, aqui estão os requisitos mínimos em 2025:

• PHP 8.2 ou superior (8.3 recomendado)
• MySQL 8.0+ ou MariaDB 10.4+ ou PostgreSQL 12+
• Limite de memória PHP de 256MB mínimo (512MB recomendado)
• Composer 2.7+

Ambiente de Staging

Nunca — e não posso enfatizar isso o suficiente — nunca execute uma migração diretamente em produção. Configure:

1. Um ambiente de staging que espelha a produção
2. Uma cópia separada do banco de dados
3. Configurações idênticas de PHP e servidor
4. Acesso ao armazenamento de arquivos (ou uma cópia de fileadmin)

# Clone seu banco de dados para staging
mysqldump -u root -p production_db | mysql -u root -p staging_db

# Rsync fileadmin
rsync -avz production:/var/www/html/fileadmin/ staging:/var/www/html/fileadmin/

Estratégia de Backup

Antes de qualquer trabalho de migração começar:

• Dump completo do banco de dados com timestamps
• Backup completo do sistema de arquivos incluindo fileadmin, typo3conf, e qualquer diretório de extensão customizada
• Documente suas configurações LocalConfiguration.php e AdditionalConfiguration.php
• Exporte seus templates TypoScript

Armazene esses backups em algum lugar completamente separado do ambiente de migração. Mantenho pelo menos três cópias.

Inventário de Extensões e Integrações

Extensões TYPO3 são provavelmente a maior fonte de dores de cabeça em migrações. Aqui está como lidar com elas.

Listar Todas as Extensões Instaladas

# Instalação baseada em Composer
composer show | grep typo3

# Ou verifique o PackageStates.php
cat typo3conf/PackageStates.php

Categorizar Cada Extensão

Para cada extensão, determine:

Categoria	Ação Necessária	Exemplo
Extensão de sistema principal	Geralmente manipulada pelo assistente de atualização	fluid_styled_content, form
Extensão TER mantida	Verifique compatibilidade com versão de destino	news, powermail, solr
Extensão TER abandonada	Encontre substituição ou solução customizada	Vários
Extensão de site customizada	Precisa de migração/reescrita manual	Seu site_package
Extensão comercial	Contacte o fornecedor para caminho de migração	in2publish, vários

Caminhos de Migração de Extensão Comuns

Algumas extensões que vejo em quase toda migração TYPO3:

• EXT:news (Georg Ringer) — Verifique compatibilidade de versão; v11+ funciona com TYPO3 v12/v13
• EXT:powermail — Extensão de formulário popular; alternativas incluem EXT:form (core)
• EXT:realurl — Descontinuada desde TYPO3 v9; substituída pelo roteamento core
• EXT:tt_address — Geralmente atualização direta
• EXT:gridelements ou EXT:flux — Estas extensões de layout causam mais dor durante atualizações. Se você está migrando para fora do TYPO3, espere trabalho significativo extraindo conteúdo de estruturas de grade.

Plano de Preservação de SEO

Pular esta seção custou a empresas milhões em tráfego orgânico. Não seja essa equipe.

Mapeamento de URL

1. Rastreie todo seu site atual com Screaming Frog, Sitebulb, ou Ahrefs
2. Exporte todos os URLs (espere milhares para sites TYPO3 grandes)
3. Crie um documento de mapeamento de URL 1:1 completo
4. Identifique suas 100 páginas principais por tráfego orgânico (verifique Google Search Console)
5. Priorize a precisão de redirecionamento para páginas de alto tráfego

Implementação de Redirecionamento

# Exemplo de redirecionamentos .htaccess
RedirectPermanent /old-typo3-path/page.html /new-path/page
RedirectPermanent /index.php?id=123 /about-us

Para redirecionamentos em larga escala, use uma solução de gerenciamento de redirecionamento em vez de amontoar milhares de regras em .htaccess. Se você está se movendo para uma pilha moderna, a maioria dos frameworks e plataformas de hospedagem (Vercel, Netlify) têm arquivos de configuração de redirecionamento.

Migração de Metadados

TYPO3 armazena metadados de SEO na tabela pages (desde que EXT:seo se tornou uma extensão core em v9):

• seo_title
• og_title, og_description, og_image
• twitter_title, twitter_description, twitter_image
• canonical_link
• no_index, no_follow

Certifique-se de exportar e mapear tudo isso. Perder suas metadescrições em 500 páginas é um desastre prevenível.

A Fase de Execução da Migração

Para Atualizações de Versão TYPO3

Siga esta sequência para cada etapa de versão:

1. Atualize as dependências Composer para a próxima versão LTS
2. Execute o Upgrade Wizard na Install Tool (Admin Tools > Upgrade)
3. Execute o analisador de banco de dados para atualizar schema
4. Verifique o log de deprecação para problemas
5. Atualize extensões para versões compatíveis
6. Corrija TypoScript deprecações e mudanças de quebra
7. Teste completamente antes de passar para a próxima etapa de versão

# Atualize o core TYPO3 via Composer
composer require typo3/cms-core:^13.4 typo3/cms-backend:^13.4 \
  typo3/cms-frontend:^13.4 --with-all-dependencies

# Execute upgrade wizards via CLI
php typo3/sysext/core/bin/typo3 upgrade:run

# Atualização de schema de banco de dados
php typo3/sysext/core/bin/typo3 database:updateschema

Para Migrações de Plataforma

Se você está migrando para uma arquitetura de CMS headless, a fase de execução se parece diferente:

1. Configure o novo CMS e configure modelos de conteúdo
2. Construa scripts de migração para transformar dados TYPO3
3. Migre conteúdo em lotes — comece com os tipos de conteúdo mais simples
4. Manipule ativos de mídia — baixe de fileadmin e faça upload para novo armazenamento de ativos
5. Construa o frontend com seu framework escolhido
6. Implemente redirecionamentos antes de go-live
7. Transição de DNS e monitoramento

Para a transformação de dados real, tipicamente escrevo scripts Python ou Node.js que leem do banco de dados TYPO3 e empurram conteúdo para o novo CMS via API:

import mysql.connector
import requests

# Conecte ao banco de dados TYPO3
db = mysql.connector.connect(
    host="localhost",
    user="typo3",
    password="password",
    database="typo3_db"
)

cursor = db.cursor(dictionary=True)
cursor.execute("""
    SELECT uid, title, description, slug, 
           seo_title, og_description 
    FROM pages 
    WHERE deleted = 0 AND hidden = 0 
    AND sys_language_uid = 0
    ORDER BY sorting
""")

for page in cursor.fetchall():
    # Transforme e empurre para novo CMS
    payload = {
        "title": page["title"],
        "slug": page["slug"],
        "seoTitle": page["seo_title"] or page["title"],
        "description": page["og_description"] or page["description"]
    }
    # POST para sua API do novo CMS
    response = requests.post(
        "https://api.new-cms.com/content",
        json=payload,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    print(f"Migrada página {page['uid']}: {response.status_code}")

Testes e Garantia de Qualidade

Checklist de Testes Automatizados

• Todas as páginas retornam códigos de status 200
• Nenhum link interno quebrado
• Todas as imagens carregam corretamente
• Formulários enviam com sucesso
• Funcionalidade de busca funciona
• Alternância de multi-idioma funciona
• Redirecionamentos de URLs antigas funcionam corretamente
• URLs canônicos estão corretos
• Sitemaps XML são válidos e acessíveis
• robots.txt está configurado adequadamente
• Certificados SSL são válidos
• Tempos de carregamento de página são aceitáveis (menos de 3 segundos)

Testes de Regressão Visual

Use ferramentas como Percy, BackstopJS, ou Playwright para comparação visual:

# Exemplo BackstopJS
npx backstop init
# Configure cenários em backstop.json
npx backstop reference  # Capture site atual
npx backstop test       # Compare após migração

Benchmarks de Desempenho

Meça antes e depois. Sua migração idealmente deveria melhorar desempenho, não degradá-lo.

Métrica	Alvo Pré-Migração	Alvo Pós-Migração
TTFB	< 800ms	< 200ms
LCP	< 2.5s	< 1.5s
CLS	< 0.1	< 0.05
FID/INP	< 200ms	< 100ms
PageSpeed Score	50-70	90+

Se você está se movendo de TYPO3 renderizado do servidor para um frontend estático ou renderizado em edge, você deveria ver melhorias dramáticas nestes números.

Monitoramento Pós-Migração

A migração não está feita quando você troca o DNS. Monitore estes por pelo menos 30 dias:

1. Google Search Console — Observe erros de rastreamento, problemas de cobertura, e problemas de indexação. Espere alguma flutuação nas primeiras duas semanas.
2. Análise — Compare padrões de tráfego semana a semana com baselines pré-migração.
3. Erros 404 — Configure logging para 404s e adicione redirecionamentos para qualquer URL que você perdeu.
4. Core Web Vitals — Monitore dados de usuário real via CrUX ou sua plataforma de análise.
5. Logs do servidor — Observe padrões de erro incomuns.

Configure alertas para quedas de tráfego excedendo 20% em qualquer página que estava anteriormente em suas 50 principais.

Armadilhas Comuns em Migrações TYPO3

Estes são erros que vi (e às vezes cometi) em dúzias de migrações:

1. Ignorar registros soft-deleted. TYPO3 usa flags deleted=1 em vez de realmente remover registros. Seus scripts de migração precisam filtrar esses, ou você importará milhares de registros que foram deletados anos atrás.

2. Esquecer de workspaces. Se o site usa workspaces TYPO3 para fluxos de trabalho editorial, você pode ter conteúdo de rascunho misturado em sua exportação. Sempre filtre para t3ver_wsid = 0 para obter apenas conteúdo live.

3. Subestimar conteúdo RTE. A saída do editor de texto rico do TYPO3 pode conter tags customizadas, tags <link> com sintaxe específica do TYPO3, e URIs t3://. Você precisa analisar e converter tudo isso.

4. Quebrar referências de arquivo. A File Abstraction Layer (FAL) do TYPO3 usa sys_file_reference para conectar arquivos ao conteúdo. Não é um simples "campo de imagem no registro de conteúdo" — é uma tabela de relação. Seus scripts de migração precisam seguir estas referências.

5. Não testar com volumes de conteúdo reais. Seu script de migração funciona ótimo com 10 páginas de teste. Ele falha catastroficamente com 15.000 páginas e 50.000 elementos de conteúdo. Sempre teste em escala.

Se você está planejando uma migração e quer evitar estas armadilhas, orientamos várias equipes empresariais através de migrações TYPO3 — sinta-se à vontade para nos contactar e podemos conversar sobre sua situação específica.

FAQ

Quanto tempo uma migração TYPO3 geralmente leva? Depende muito da complexidade de sua instalação. Uma atualização TYPO3 v11 para v13 direta para um site single-language com extensões padrão pode levar 4-6 semanas. Uma migração de plataforma completa de um site TYPO3 empresarial multi-idioma com extensões customizadas facilmente pode levar 3-6 meses. A fase de auditoria de conteúdo sozinha pode levar 2-4 semanas para sites grandes.

Posso pular versões TYPO3 LTS durante uma atualização? Tecnicamente, você não deveria. A recomendação oficial é atualizar através de cada versão LTS sequencialmente (v8 → v9 → v10 → v11 → v12 → v13) porque cada versão inclui upgrade wizards que lidam com migrações de dados para esse passo específico. Pular versões significa que essas migrações de dados não rodam, e você terminará com dados corrompidos ou órfãos. Algumas agências afirmam que podem fazer atualizações pulando versão, mas vi isso causar problemas sutis de dados que surgem meses depois.

Devo migrar de TYPO3 para WordPress? Depende de suas necessidades. WordPress lida bem com sites de marketing simples, mas se você escolheu TYPO3 originalmente porque tinha requisitos de multi-idioma complexos, permissões granulares, ou fluxos de trabalho empresariais, WordPress pode ser um passo para trás. Considere se um CMS headless emparelhado com um framework de frontend moderno pode não ser um melhor ajuste. Escrevemos sobre abordagens de desenvolvimento CMS headless que frequentemente fazem mais sentido para equipes deixando plataformas de CMS empresariais.

O que acontece com meus rankings de SEO durante uma migração TYPO3? Espere alguma flutuação de ranking para 2-6 semanas, mesmo com redirecionamentos perfeitos. Google precisa de tempo para rastrear novamente e reindexar seu conteúdo. Para minimizar o impacto: implemente redirecionamentos 301 para cada URL, mantenha sua estrutura de conteúdo o mais próxima possível da original, envie sitemaps atualizados imediatamente, e use a ferramenta Change of Address no Google Search Console se você estiver mudando domínios. Sites que lidam com redirecionamentos corretamente tipicamente se recuperam em 4-8 semanas.

Como faço para lidar com extensões TYPO3 que não existem na plataforma de destino? Primeiro, determine o que a extensão realmente faz. Muitas extensões TYPO3 fornecem funcionalidade que está integrada em plataformas modernas (como construtores de formulários, ferramentas de SEO, ou gerenciamento de redirecionamentos). Para funcionalidade customizada, você precisará encontrar um plugin/serviço equivalente ou construir features customizadas. Crie uma planilha listando cada extensão, seu propósito, e a estratégia de substituição.

Vale a pena se mover para TYPO3 headless em vez de migrar completamente? A extensão TYPO3 headless (EXT:headless) é uma opção legítima se sua equipe está confortável com o backend TYPO3 mas quer um frontend moderno. Expõe conteúdo TYPO3 como APIs JSON, permitindo você construir seu frontend com Next.js, Nuxt, ou Astro. Esta abordagem preserva sua estrutura de conteúdo existente e fluxos de trabalho editoriais enquanto moderniza a camada de apresentação. É um bom meio termo, embora signifique que você ainda estará mantendo um backend TYPO3.

Qual é o custo de uma migração TYPO3 em 2025? Números aproximados: uma atualização de versão TYPO3 para um site de tamanho médio custa $15.000-$50.000. Uma migração de plataforma completa para uma arquitetura headless varia de $40.000-$150.000+ dependendo do volume de conteúdo, número de idiomas, funcionalidade customizada, e complexidade de integração. Estes não são números pequenos, mas compare-os contra o custo de manter uma instalação de CMS desatualizada e insegura. Você pode checar nossa página de pricing para mais detalhes sobre como estruturamos estes projetos.

Preciso reconstruir meus templates do zero? Para atualizações de versão TYPO3, geralmente não completamente — mas você precisará atualizar templates Fluid para lidar com ViewHelpers descontinuados e novas APIs. Para migrações de plataforma, sim, você está construindo um novo frontend. A boa notícia é que frameworks modernos como Next.js e Astro tornam significativamente mais rápido construir frontends performáticos do que era na era Fluid/TypoScript. Seu design pode permanecer o mesmo; a implementação apenas muda.