Migración de TYPO3: Lista de Verificación Completa del Desarrollador

He pasado por suficientes migraciones de TYPO3 para saber que la diferencia entre una transición suave y una pesadilla de seis meses se reduce a la preparación. TYPO3 es un CMS poderoso — ha existido desde 1998 y ejecuta algunos sitios empresariales muy complejos, especialmente en la región DACH. Pero cuando llega el momento de migrar, ya sea que esté actualizando entre versiones principales de TYPO3 o moviendo a una plataforma completamente diferente, el proceso puede volverse feo rápidamente si no tiene un plan.

Esta es la lista de verificación que desearía que alguien me hubiera entregado antes de mi primera migración de TYPO3. No es teórica. Cada elemento aquí existe porque he visto lo que sucede cuando lo omites.

Tabla de Contenidos

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide

Evalúe su instalación actual de TYPO3

Antes de tocar nada, necesita entender exactamente con qué está trabajando. Esto suena obvio. No lo es. He entrado en proyectos donde el equipo ni siquiera sabía qué versión de TYPO3 estaban ejecutando en producción.

Auditoría de versión y entorno

Comience aquí:

# Compruebe su versión de TYPO3
php typo3/sysext/core/bin/typo3 --version

# O compruebe a través del backend: Ayuda > Acerca de TYPO3

Documente lo siguiente:

  • Versión de TYPO3 (principal y secundaria — p. ej., TYPO3 v11.5.38 LTS)
  • Versión de PHP que se ejecuta en el servidor
  • Tipo y versión de base de datos (MySQL, MariaDB, PostgreSQL)
  • Servidor web (Apache, Nginx)
  • Instalación basada en Composer o clásica — esto es enormemente importante
  • Número de sitios/dominios en la instalación (las configuraciones multisitio agregan complejidad)
  • Número total de páginas y elementos de contenido en el árbol de páginas

Mapeo de usuarios y permisos

El sistema de permisos de usuarios y grupos del backend de TYPO3 es notoriamente granular. Exporte sus tablas be_users y be_groups y documente:

  • Cuántos usuarios de backend existen
  • Qué permisos personalizados están configurados
  • Qué usuarios tienen acceso de administrador
  • Cualquier anulación de TSconfig personalizada

Si está migrando a un CMS diferente, deberá asignar estos roles al modelo de permisos del nuevo sistema. Si está actualizando versiones de TYPO3, algunas configuraciones de permisos pueden necesitar actualización.

Complejidad de TypoScript y configuración

Ejecute una auditoría rápida de su configuración de TypoScript:

# Cuente sus archivos de TypoScript
find . -name '*.typoscript' -o -name '*.ts' | wc -l

# Compruebe setup.txt y constants.txt (formato heredado)
find . -name 'setup.txt' -o -name 'constants.txt' | wc -l

Si tiene cientos de archivos de TypoScript con configuraciones profundamente anidadas, espere que la migración tome más tiempo. He visto instalaciones de TYPO3 con más de 10,000 líneas de TypoScript que evolucionaron durante 15 años. Eso no es un proyecto de fin de semana.

Defina su estrategia de migración

Hay fundamentalmente tres tipos de migraciones de TYPO3, y debe decidir cuál está haciendo antes que nada.

Tipo de migración Cuándo elegir Complejidad Cronograma típico
Actualización de versión de TYPO3 (p. ej., v10 → v12) Desea permanecer en TYPO3 Media-Alta 4-12 semanas
TYPO3 a CMS headless (p. ej., Contentful, Strapi, Sanity) Desea flexibilidad moderna del frontend Alta 8-20 semanas
TYPO3 a otro CMS tradicional (p. ej., WordPress, Drupal) Desea un CMS monolítico diferente Media 6-16 semanas
TYPO3 a TYPO3 headless (usando EXT:headless) Desea backend TYPO3 con frontend moderno Media 6-14 semanas

Actualización dentro de TYPO3

Si se queda en TYPO3, la ruta de actualización oficial requiere pasar por cada versión LTS. No puede pasar de v8 a v12 directamente. Bueno, puede intentarlo. No lo haga.

La ruta recomendada a partir de 2025:

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

TYPO3 v13 LTS fue lanzado a finales de 2024 y es la versión actual de soporte a largo plazo. TYPO3 v12 LTS recibirá actualizaciones de seguridad hasta abril de 2026 a través del programa Extended Long Term Support (ELTS).

Migración desde TYPO3

Si se está moviendo a una arquitectura headless — y honestamente, para muchos equipos esto tiene mucho sentido — querrá evaluar sus opciones de marco de frontend. Hemos realizado un trabajo extenso con Next.js y Astro como capas de frontend emparejadas con plataformas de CMS headless.

La pregunta clave es: ¿justifica su modelo de contenido la complejidad de TYPO3? Si está ejecutando un sitio de marketing con 200 páginas, TYPO3 probablemente sea excesivo. Si está ejecutando un portal empresarial multilingüe complejo con flujos de trabajo intrincados, el trabajo de modelado de contenido durante la migración será significativo independientemente de a dónde vaya.

Auditoría de contenido y mapeo de datos

Aquí es donde las migraciones viven o mueren. El contenido.

Exportación y análisis de base de datos

TYPO3 almacena contenido principalmente en estas tablas:

  • pages — la estructura del árbol de páginas
  • tt_content — elementos de contenido
  • sys_file y sys_file_reference — activos de medios (FAL)
  • sys_category — categorías
  • tx_news_domain_model_news — si está utilizando la extensión de noticias

Exporte su contenido y obtenga números reales:

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

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

-- Cuente referencias de archivo
SELECT COUNT(*) FROM sys_file WHERE missing = 0;

Mapeo de tipos de contenido

Cree una hoja de cálculo que asigne todos los tipos de contenido de TYPO3 (CType) a sus equivalentes en el sistema de destino. Los tipos de contenido comunes de TYPO3 que encontrará:

  • text, textmedia, textpic — contenido de texto estándar
  • image — galerías de imágenes
  • table — tablas de datos
  • bullets — listas
  • uploads — listas de archivos
  • html — HTML sin procesar (estos siempre son divertidos durante la migración)
  • list — contenido del complemento (aquí es donde se complica)
  • Tipos de contenido personalizados de extensiones

El list CType es el complicado. Representa contenido de complemento — listados de noticias, formularios, funcionalidad personalizada — y cada uno necesita atención individual.

Contenido multilingüe

TYPO3 maneja traducciones a través del modo conectado (donde las traducciones están vinculadas a un registro de idioma predeterminado) o modo libre. Compruebe qué enfoque usa su sitio:

-- Compruebe la configuración de traducción
SELECT sys_language_uid, COUNT(*) 
FROM pages 
WHERE deleted = 0 
GROUP BY sys_language_uid;

Si tiene 8 idiomas con traducciones en modo conectado, el mapeo de datos de su migración acaba de volverse 8 veces más complejo. Planifique en consecuencia.

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide - architecture

Preparación de la infraestructura técnica

Requisitos del servidor

Si está actualizando a TYPO3 v13, estos son los requisitos mínimos a partir de 2025:

  • PHP 8.2 o superior (8.3 recomendado)
  • MySQL 8.0+ o MariaDB 10.4+ o PostgreSQL 12+
  • Límite de memoria PHP de 256 MB mínimo (512 MB recomendado)
  • Composer 2.7+

Entorno de ensayo

Nunca — y no puedo enfatizar esto lo suficiente — nunca ejecute una migración directamente en producción. Configure:

  1. Un entorno de ensayo que refleje la producción
  2. Una copia de base de datos separada
  3. Configuraciones idénticas de PHP y servidor
  4. Acceso a almacenamiento de archivos (o una copia de fileadmin)
# Clone su base de datos al ensayo
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/

Estrategia de copia de seguridad

Antes de que comience cualquier trabajo de migración:

  • Volcado completo de base de datos con marcas de tiempo
  • Copia de seguridad completa del sistema de archivos, incluidos fileadmin, typo3conf y cualquier directorio de extensión personalizada
  • Documente su configuración LocalConfiguration.php y AdditionalConfiguration.php
  • Exporte sus plantillas de TypoScript

Almacene estas copias de seguridad en algún lugar completamente separado del entorno de migración. Mantengo al menos tres copias.

Inventario de extensiones e integraciones

Las extensiones de TYPO3 son probablemente la mayor fuente de dolores de cabeza de migración. Así es como manejarlas.

Liste todas las extensiones instaladas

# Instalación basada en Composer
composer show | grep typo3

# O compruebe PackageStates.php
cat typo3conf/PackageStates.php

Categorice cada extensión

Para cada extensión, determine:

Categoría Acción requerida Ejemplo
Extensión del sistema central Generalmente manejada por el asistente de actualización fluid_styled_content, form
Extensión TER mantenida Compruebe compatibilidad con versión de destino news, powermail, solr
Extensión TER abandonada Encuentre un reemplazo o solución personalizada Varios
Extensión de sitio personalizada Necesita migración/reescritura manual Su site_package
Extensión comercial Contacte al proveedor para la ruta de migración in2publish, varios

Rutas comunes de migración de extensiones

Algunas extensiones que veo en casi todas las migraciones de TYPO3:

  • EXT:news (Georg Ringer) — Compruebe compatibilidad de versión; v11+ funciona con TYPO3 v12/v13
  • EXT:powermail — Extensión de formulario popular; las alternativas incluyen EXT:form (núcleo)
  • EXT:realurl — Deprecada desde TYPO3 v9; reemplazada por enrutamiento central
  • EXT:tt_address — Generalmente una actualización directa
  • EXT:gridelements o EXT:flux — Estas extensiones de diseño causando el mayor dolor durante actualizaciones. Si está migrando desde TYPO3, espere un trabajo significativo extrayendo contenido de estructuras de cuadrícula.

Plan de preservación de SEO

Omitir esta sección le ha costado a las empresas millones en tráfico orgánico. No sea ese equipo.

Mapeo de URL

  1. Rastree todo su sitio actual con Screaming Frog, Sitebulb o Ahrefs
  2. Exporte todas las URL (espere miles para sitios TYPO3 grandes)
  3. Cree un documento de mapeo de URL 1:1 completo
  4. Identifique sus 100 páginas principales por tráfico orgánico (compruebe la Consola de búsqueda de Google)
  5. Priorice la precisión de redirección para páginas de alto tráfico

Implementación de redirección

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

Para redirecciones a gran escala, use una solución de gestión de redirección en lugar de amontonar miles de reglas en .htaccess. Si se está moviendo a un stack moderno, la mayoría de plataformas de alojamiento (Vercel, Netlify) tienen archivos de configuración de redirección.

Migración de metadatos

TYPO3 almacena metadatos de SEO en la tabla pages (desde que EXT:seo se convirtió en una extensión central en v9):

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

Asegúrese de exportar y asignar todo esto. Perder sus metadescripciones en 500 páginas es un desastre prevenible.

La fase de ejecución de la migración

Para actualizaciones de versión de TYPO3

Siga esta secuencia para cada paso de versión:

  1. Actualice las dependencias de Composer a la siguiente versión LTS
  2. Ejecute el Asistente de actualización en la herramienta de instalación (Herramientas de administrador > Actualización)
  3. Ejecute el analizador de base de datos para actualizar el esquema
  4. Compruebe el registro de deprecación para problemas
  5. Actualice extensiones a versiones compatibles
  6. Arregle TypoScript deprecaciones y cambios importantes
  7. Pruebe a fondo antes de pasar al siguiente paso de versión
# Actualice el núcleo de TYPO3 a través de Composer
composer require typo3/cms-core:^13.4 typo3/cms-backend:^13.4 \
  typo3/cms-frontend:^13.4 --with-all-dependencies

# Ejecute asistentes de actualización mediante CLI
php typo3/sysext/core/bin/typo3 upgrade:run

# Actualización del esquema de base de datos
php typo3/sysext/core/bin/typo3 database:updateschema

Para migraciones de plataforma

Si está migrando a una arquitectura de CMS headless, la fase de ejecución se ve diferente:

  1. Configure el nuevo CMS y configure modelos de contenido
  2. Cree scripts de migración para transformar datos de TYPO3
  3. Migre contenido en lotes — comience con los tipos de contenido más simples
  4. Maneje activos de medios — descargue de fileadmin y cargue al nuevo almacenamiento de activos
  5. Construya el frontend con su marco de trabajo elegido
  6. Implemente redirecciones antes del lanzamiento
  7. Cambio de DNS y monitoreo

Para la transformación de datos real, típicamente escribo scripts de Python o Node.js que leen desde la base de datos de TYPO3 e insertan contenido en el nuevo CMS a través de API:

import mysql.connector
import requests

# Conecte a la base de datos de 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 inserte en el nuevo CMS
    payload = {
        "title": page["title"],
        "slug": page["slug"],
        "seoTitle": page["seo_title"] or page["title"],
        "description": page["og_description"] or page["description"]
    }
    # INSERTE en su API de CMS nueva
    response = requests.post(
        "https://api.new-cms.com/content",
        json=payload,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    print(f"Página migrada {page['uid']}: {response.status_code}")

Pruebas y garantía de calidad

Lista de verificación de pruebas automatizadas

  • Todas las páginas devuelven códigos de estado 200
  • Sin enlaces internos rotos
  • Todas las imágenes se cargan correctamente
  • Los formularios se envían correctamente
  • La funcionalidad de búsqueda funciona
  • El cambio de idioma múltiple funciona
  • Las redirecciones desde URL antiguas funcionan correctamente
  • Las URL canónicas son correctas
  • Los mapas del sitio XML son válidos y accesibles
  • robots.txt está configurado correctamente
  • Los certificados SSL son válidos
  • Los tiempos de carga de página son aceptables (menos de 3 segundos)

Pruebas de regresión visual

Use herramientas como Percy, BackstopJS o Playwright para comparación visual:

# Ejemplo de BackstopJS
npx backstop init
# Configure escenarios en backstop.json
npx backstop reference  # Capture el sitio actual
npx backstop test       # Compare después de la migración

Puntos de referencia de rendimiento

Mida antes y después. Su migración idealmente debería mejorar el rendimiento, no degradarlo.

Métrica Objetivo previa a migración Objetivo posterior a migración
TTFB < 800ms < 200ms
LCP < 2.5s < 1.5s
CLS < 0.1 < 0.05
FID/INP < 200ms < 100ms
Puntuación de PageSpeed 50-70 90+

Si se está moviendo de TYPO3 renderizado en el servidor a un frontend estático o renderizado en el borde, debería ver mejoras dramáticas en estos números.

Monitoreo posterior a la migración

La migración no se completa cuando voltea el DNS. Monitoree esto durante al menos 30 días:

  1. Google Search Console — Vigile errores de rastreo, problemas de cobertura y problemas de indexación. Espere cierta fluctuación en las primeras dos semanas.
  2. Análisis — Compare patrones de tráfico semana a semana con las líneas de base anteriores a la migración.
  3. Errores 404 — Configure registro para 404 y agregue redirecciones para cualquier URL que haya pasado por alto.
  4. Core Web Vitals — Monitoree datos de usuarios reales a través de CrUX o su plataforma de análisis.
  5. Registros del servidor — Vigile patrones de error inusuales.

Configure alertas para caídas de tráfico superiores al 20% en cualquier página que estuvo previamente en sus 50 principales.

Escollos comunes de migración de TYPO3

Estos son errores que he visto (y a veces cometido) en docenas de migraciones:

1. Ignorar registros eliminados de forma suave. TYPO3 usa banderas deleted=1 en lugar de eliminar realmente registros. Sus scripts de migración necesitan filtrar estos, o importará miles de registros que fueron eliminados hace años.

2. Olvidarse de los espacios de trabajo. Si el sitio usa espacios de trabajo de TYPO3 para flujos de trabajo editoriales, es posible que tenga contenido borrador mezclado en su exportación. Siempre filtre por t3ver_wsid = 0 para obtener solo contenido en vivo.

3. Subestimar el contenido RTE. La salida del editor de texto enriquecido de TYPO3 puede contener etiquetas personalizadas, etiquetas <link> con sintaxis específica de TYPO3 y URI t3://. Necesita analizar y convertir todos estos.

4. Romper referencias de archivo. La capa de abstracción de archivo de TYPO3 (FAL) usa sys_file_reference para conectar archivos al contenido. No es un simple "campo de imagen en el registro de contenido" — es una tabla de relación. Sus scripts de migración necesitan seguir estas referencias.

5. No probar con volúmenes de contenido reales. Su script de migración funciona perfectamente con 10 páginas de prueba. Falla catastróficamente con 15,000 páginas y 50,000 elementos de contenido. Siempre pruebe a escala.

Si está planeando una migración y desea evitar estos escollos, hemos guiado a varios equipos empresariales a través de migraciones de TYPO3 — no dude en ponerse en contacto y podemos hablar sobre su situación específica.

Preguntas frecuentes

¿Cuánto tiempo típicamente tarda una migración de TYPO3? Depende en gran medida de la complejidad de su instalación. Una actualización sencilla de TYPO3 v11 a v13 para un sitio de un solo idioma con extensiones estándar podría tomar 4-6 semanas. Una migración completa de plataforma de un sitio TYPO3 empresarial multilingüe con extensiones personalizadas puede fácilmente tomar 3-6 meses. La fase de auditoría de contenido por sí sola puede tomar 2-4 semanas para sitios grandes.

¿Puedo omitir versiones LTS de TYPO3 durante una actualización? Técnicamente, no debería. La recomendación oficial es actualizar a través de cada versión LTS secuencialmente (v8 → v9 → v10 → v11 → v12 → v13) porque cada versión incluye asistentes de actualización que manejan migraciones de datos para ese paso específico. Omitir versiones significa que esas migraciones de datos no se ejecutan, y terminará con datos corruptos u huérfanos. Algunas agencias afirman que pueden hacer actualizaciones de omisión de versión, pero he visto que causa problemas de datos sutiles que aparecen meses después.

¿Debería migrar de TYPO3 a WordPress? Depende de sus necesidades. WordPress maneja bien sitios de marketing simples, pero si originalmente eligió TYPO3 debido a requisitos complejos multilingües, permisos granulares o flujos de trabajo empresariales, WordPress podría ser un paso atrás. Considere si un CMS headless emparejado con un marco de frontend moderno podría ser mejor. Hemos escrito sobre enfoques de desarrollo de CMS headless que a menudo tienen más sentido para equipos que dejan plataformas de CMS empresariales.

¿Qué sucede con mis clasificaciones de SEO durante una migración de TYPO3? Espere cierta fluctuación de clasificación durante 2-6 semanas, incluso con redirecciones perfectas. Google necesita tiempo para rastrear y reindexar su contenido. Para minimizar el impacto: implemente redirecciones 301 para cada URL, mantenga la estructura de contenido lo más cercana posible a la original, envíe mapas del sitio actualizados inmediatamente y use la herramienta Cambio de dirección en Google Search Console si está cambiando dominios. Los sitios que manejan redirecciones correctamente típicamente se recuperan dentro de 4-8 semanas.

¿Cómo manejo extensiones de TYPO3 que no existen en la plataforma de destino? Primero, determine qué hace realmente la extensión. Muchas extensiones de TYPO3 proporcionan funcionalidad que está integrada en plataformas modernas (como constructores de formularios, herramientas de SEO o gestión de redirecciones). Para funcionalidad personalizada, deberá encontrar un complemento/servicio equivalente o crear características personalizadas. Cree una hoja de cálculo listando cada extensión, su propósito y la estrategia de reemplazo.

¿Vale la pena pasar a TYPO3 headless en lugar de migrar completamente? La extensión headless de TYPO3 (EXT:headless) es una opción legítima si su equipo se siente cómodo con el backend de TYPO3 pero quiere un frontend moderno. Expone contenido de TYPO3 como API JSON, permitiéndole construir su frontend con Next.js, Nuxt o Astro. Este enfoque preserva su estructura de contenido existente y flujos de trabajo editoriales mientras moderniza la capa de presentación. Es un buen término medio, aunque significa que aún está manteniendo un backend TYPO3.

¿Cuál es el costo de una migración de TYPO3 en 2025? Cifras aproximadas: una actualización de versión de TYPO3 para un sitio de tamaño medio cuesta $15,000-$50,000. Una migración completa de plataforma a una arquitectura headless oscila entre $40,000-$150,000+ dependiendo del volumen de contenido, número de idiomas, funcionalidad personalizada y complejidad de integración. Estos no son números pequeños, pero compárelos contra el costo de mantener una instalación de CMS desactualizada e insegura. Puede verificar nuestra página de precios para más detalles sobre cómo estructuramos estos proyectos.

¿Necesito reconstruir mis plantillas desde cero? Para actualizaciones de versión de TYPO3, generalmente no completamente — pero deberá actualizar plantillas Fluid para manejar ViewHelpers deprecados y API nuevas. Para migraciones de plataforma, sí, está construyendo un nuevo frontend. La buena noticia es que marcos modernos como Next.js y Astro hacen que sea significativamente más rápido construir frontends de rendimiento que lo que fue en la era Fluid/TypoScript. Su diseño puede permanecer igual; la implementación simplemente cambia.