Buscar y reemplazar URL en WordPress al cambiar de dominio

Si el traslado es también una reconstrucción del sitio, consulta nuestro servicio de migración de sitios web a Astro y Next.js.

#1. Por qué REPLACE en SQL rompe los datos serializados de WordPress

WordPress guarda muchas opciones de configuración, disposiciones de widgets y propiedades del tema en la tabla wp_options (y en wp_postmeta, wp_usermeta y wp_termmeta) como arrays u objetos serializados. Una cadena PHP serializada declara el tipo de dato y la longitud en bytes de cada valor de texto.

#Cómo guarda la longitud una cadena PHP serializada

Fíjate en esta cadena serializada, que guarda un ajuste de dominio: s:22:"https://old-domain.com";

En esta estructura:

• s declara que el tipo es una cadena (string).
• 22 indica que el valor mide exactamente 22 bytes.
• "https://old-domain.com" es el propio valor.

Un array de opciones del tema con la URL del logotipo queda así una vez serializado: a:2:{s:11:"theme_color";s:4:"blue";s:8:"logo_url";s:28:"http://dev.site.com/logo.png";}

Cada clave y cada valor llevan su longitud: theme_color ocupa 11 bytes, logo_url 8 y la URL 28.

#Por qué una longitud incorrecta hace que WordPress descarte la opción

Si ejecutas un REPLACE normal en SQL para cambiar el dominio, por ejemplo de old-domain.com a my-new-company-domain.com, la consulta reescribe el valor pero deja intacto el marcador de longitud: s:22:"https://my-new-company-domain.com";

El valor nuevo mide 33 bytes, pero el marcador sigue diciendo 22. Cuando WordPress lee la fila, la pasa por maybe_unserialize(). PHP lee 22 bytes (https://my-new-company), espera la comilla de cierre, encuentra un guion y unserialize() devuelve false. La opción que esperaba el tema o el plugin llega como false, así que el tema vuelve a sus valores predeterminados, los widgets desaparecen de las barras laterales, se pierden los ajustes del Personalizador (que el tema guarda serializados en wp_options) y algunos plugins vuelven a pedir su clave de licencia.

Lo mismo ocurre en sentido contrario. Si en el ejemplo del logotipo sustituyes dev.site.com por site.com, obtienes una URL de 24 bytes bajo un marcador que sigue diciendo 28, y todo el array queda ilegible, no solo el logotipo.

Un reemplazo solo sobrevive a un REPLACE en SQL cuando la cadena antigua y la nueva tienen exactamente la misma longitud, y eso es una casualidad, no un método.

#Objetos serializados y __PHP_Incomplete_Class

Si una cadena serializada representa un objeto: O:31:"WPPoland\Database\CustomObject":1:{...}

PHP asocia el nombre de clase guardado con una clase cargada en tiempo de ejecución. Si la clase no está cargada en el momento de deserializar el valor (por ejemplo, porque el plugin que la define está desactivado o porque la migración cambió su espacio de nombres), PHP crea en su lugar un marcador __PHP_Incomplete_Class. Sus métodos no se pueden llamar, y el código que espera el objeto real falla. Las herramientas compatibles con la serialización deserializan y vuelven a serializar estos valores; no renombran clases.

#2. Cómo cambiar el dominio de WordPress con WP-CLI

WP-CLI incluye el comando search-replace. Su referencia oficial indica que “gestiona de forma inteligente los datos serializados de PHP y no cambia los valores de las claves primarias” (referencia de comandos de WP-CLI, traducción propia). Es el método habitual para actualizar las URL en la base de datos de WordPress.

#Paso 1: exportar una copia de seguridad de la base de datos

Antes de tocar ninguna fila, exporta una copia completa en SQL:

# Exportar la base de datos a un archivo SQL
wp db export backup-pre-domain-migration.sql

Si en el servidor no hay WP-CLI pero sí acceso a MySQL, mysqldump produce el mismo tipo de volcado.

#Paso 2: simular el reemplazo con —dry-run

Ejecuta primero el comando con --dry-run. Según la referencia, con esta opción el comando “ejecuta toda la operación de búsqueda y reemplazo y muestra el informe, pero no guarda los cambios en la base de datos” (traducción propia).

# Simulación: informa de lo que cambiaría, no escribe nada
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid --dry-run

El informe es una tabla con las columnas Table, Column, Replacements y Type, una fila por cada columna que contiene coincidencias, seguida de una línea como Success: 245 replacements to be made. (las cifras dependen por completo de tu sitio). La columna Type muestra SQL o PHP: el motor que procesó esa columna.

#Qué hace realmente —precise

La referencia describe --precise así: “fuerza el uso de PHP (en lugar de SQL) en todas las columnas” (traducción propia). Por defecto, el comando “usa consultas SQL rápidas, pero cambia automáticamente a PHP en las columnas que contienen datos serializados” (traducción propia). Por tanto, no necesitas --precise para proteger los valores serializados: WP-CLI ya los detecta. Usa --precise cuando quieras procesar todo en PHP, por ejemplo si no te fías de la detección en una columna con contenido poco habitual, y asume que la ejecución tardará más.

#Qué tablas: por defecto, —all-tables y —all-tables-with-prefix

Por defecto, el comando trabaja solo con las tablas registradas en el objeto $wpdb, es decir, las tablas del núcleo más las de los plugins que se registran ahí. Dos opciones amplían el alcance:

Muchos plugins crean sus propias tablas sin registrarlas en $wpdb, así que una ejecución por defecto puede dejar sin cambiar las URL guardadas ahí. --all-tables-with-prefix es la forma más segura de incluirlas. Usa --all-tables solo cuando la base de datos pertenezca a este único sitio: si dos instalaciones de WordPress comparten base de datos con prefijos distintos, --all-tables reescribe también las URL del otro sitio.

#Por qué hay que excluir la columna guid

La documentación de WordPress sobre el traslado de un sitio es tajante con la columna guid de wp_posts: “nunca, jamás, cambies el contenido de la columna GUID, bajo ninguna circunstancia” (Moving WordPress, developer.wordpress.org, traducción propia). El GUID identifica una entrada ante los lectores de feeds; si cambia, esos lectores muestran entradas antiguas como nuevas. La referencia de WP-CLI usa precisamente este caso como ejemplo para excluir una columna: --skip-columns=guid.

#Paso 3: ejecutar el reemplazo

Si el informe de la simulación es correcto, ejecuta el mismo comando sin --dry-run. --skip-columns acepta también nombres con la tabla delante (table.column), y --skip-tables excluye tablas enteras, algo útil en bases de datos grandes con tablas de registros:

# Ejecutar, conservar los GUID e incluir tablas de plugins no registradas con el prefijo del sitio
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid

Para generar un archivo SQL ya migrado sin tocar la base de datos en producción, usa --export, que según la referencia escribe “los datos transformados como archivo SQL en lugar de guardar los reemplazos en la base de datos” (traducción propia):

wp search-replace 'https://old-domain.com' 'https://new-domain.com' --skip-columns=guid --export=migrated.sql

#Paso 4: corregir el contenido mixto tras pasar a HTTPS

Si el sitio pasa además de HTTP a HTTPS, ejecuta una segunda pasada para las referencias inseguras escritas a mano:

# Sustituir los enlaces HTTP antiguos por enlaces HTTPS en el dominio nuevo
wp search-replace 'http://old-domain.com' 'https://new-domain.com' --all-tables-with-prefix --skip-columns=guid

Sin esta pasada, el navegador bloquea o marca como inseguros los recursos (imágenes, scripts y hojas de estilo) que siguen cargándose por HTTP.

#Paso 5: regenerar los enlaces permanentes y vaciar la caché de objetos

Tras una ejecución correcta, WP-CLI muestra el aviso Please remember to flush your persistent object cache with wp cache flush cuando hay una caché de objetos activa. Hazlo, regenera las reglas de reescritura y comprueba las URL guardadas:

wp rewrite flush
wp cache flush
wp option get home
wp option get siteurl

wp rewrite flush equivale a guardar sin cambios la pantalla Ajustes > Enlaces permanentes en el escritorio.

#Cambio de dominio en WordPress multisitio

En una instalación multisitio, añade --network para recorrer “todas las tablas registradas en $wpdb en una instalación multisitio” (traducción propia). El multisitio guarda además el dominio de cada sitio, sin protocolo, en la columna domain de wp_blogs y wp_site, y el dominio de la red en la constante DOMAIN_CURRENT_SITE de wp-config.php. Una búsqueda de https://old-domain.com no coincide con un old-domain.com sin protocolo en esas columnas, así que revísalas, y también la constante, por separado. La documentación de WordPress sobre el cambio de la URL del sitio advierte de que sus instrucciones “son solo para instalaciones individuales de WordPress” (traducción propia).

#3. Definir WP_HOME y WP_SITEURL en wp-config.php

Si la base de datos todavía contiene el dominio antiguo pero necesitas cargar el sitio con el nuevo, puedes sobrescribir ambos valores en wp-config.php. La documentación de wp-config.php indica que WP_SITEURL “sobrescribe el valor de siteurl de la tabla wp_options” y que WP_HOME sobrescribe el valor de home, “pero no lo cambia en la base de datos” (traducción propia). El valor home es la dirección que escriben los visitantes; siteurl es la dirección donde residen los archivos del núcleo. Ambos deben incluir https:// y no terminar en barra.

#Sobrescritura temporal de las URL en wp-config.php en staging

La sobrescritura cambia el enrutamiento y las URL de los recursos, no las filas guardadas. Los enlaces dentro del contenido de las entradas, los metadatos y los ajustes de los plugins siguen apuntando al dominio antiguo hasta que ejecutas un buscar y reemplazar. La documentación advierte también de que “la URL volverá al valor antiguo de la base de datos si alguna vez se elimina esta línea de wp-config” (traducción propia). Trata las constantes como una forma de entrar en el escritorio y ejecuta el reemplazo completo antes del lanzamiento:

// Override the stored URLs while the database still holds the old domain
define( 'WP_HOME', 'https://new-domain.com' );
define( 'WP_SITEURL', 'https://new-domain.com' );

Mientras las constantes estén definidas, los dos campos de URL de Ajustes > Generales no se pueden editar, porque los valores están fijados en el código.

#Definir la URL del sitio a partir del nombre de host actual

La documentación muestra una forma dinámica basada en $_SERVER['HTTP_HOST'], útil cuando un mismo código se ejecuta en local, en staging y en producción:

define( 'WP_HOME', 'https://' . $_SERVER['HTTP_HOST'] );
define( 'WP_SITEURL', 'https://' . $_SERVER['HTTP_HOST'] );

Viene con una advertencia: HTTP_HOST “lo crea PHP de forma dinámica a partir del valor de la cabecera HTTP Host de la petición, lo que puede permitir vulnerabilidades de inclusión de archivos” (traducción propia). Cuando Apache funciona con UseCanonicalName On, SERVER_NAME procede de la configuración del servidor, y la documentación lo considera la opción más segura en ese caso. En un servidor de producción público, usa mejor un valor fijo o una lista de hosts permitidos.

#Otras formas de cambiar la URL del sitio: wp option update, RELOCATE y functions.php

La guía Moving WordPress de WordPress enumera varias formas de cambiar los dos valores guardados:

• WP-CLI: wp option update home 'https://example.com' y wp option update siteurl 'https://example.com'. Escribe los valores en wp_options y no cambia nada más.
• functions.php: añade temporalmente update_option( 'siteurl', ... ) y update_option( 'home', ... ) al tema activo, carga el sitio unas cuantas veces y elimina el código. La guía lo dice sin rodeos: “no dejes este código en el archivo functions.php” (traducción propia).
• RELOCATE: añade define( 'RELOCATE', true ); a wp-config.php, inicia sesión a través de wp-login.php en la dirección nueva, revisa los dos campos de Ajustes > Generales y elimina la línea. La guía considera inseguro dejarla y señala que solo actualiza la URL del sitio, así que las demás referencias siguen necesitando un buscar y reemplazar.
• Edición directa en la base de datos: tras una copia de seguridad, edita las filas siteurl y home de la tabla de opciones en phpMyAdmin (el prefijo de la tabla puede no ser wp_).

Ninguna de estas vías toca las URL dentro del contenido, por eso el buscar y reemplazar de la sección 2 sigue siendo el paso principal.

#4. Buscar y reemplazar sin SSH: Better Search Replace y Search Replace DB

La guía de migración de WordPress nombra dos alternativas a WP-CLI para alojamientos sin acceso a la consola.

#Plugin Better Search Replace

Si todavía puedes entrar en el escritorio, el plugin Better Search Replace ejecuta un reemplazo compatible con la serialización desde Herramientas > Better Search Replace:

1. Instala y activa el plugin.
2. Escribe la URL antigua en el campo Search for y la nueva en Replace with.
3. Selecciona las tablas que quieres procesar.
4. Deja marcada la casilla Run as dry run? en la primera pasada y revisa el informe.
5. Desmarca la simulación y vuelve a ejecutarlo.

Sus ventajas son claras: no requiere SSH ni WP-CLI, tiene una interfaz visual y trae el modo de simulación integrado. A cambio, se ejecuta dentro de peticiones PHP, así que en tablas muy grandes es más lento y puede chocar con el límite de tiempo de ejecución del alojamiento, y no sirve de nada cuando el escritorio ya redirige al dominio antiguo.

#Script Search Replace DB de interconnect/it

Cuando no hay ni WP-CLI ni escritorio, la guía remite al script de interconnect/it “para cambiar de forma segura todas las apariciones de tu dominio o ruta antiguos por los nuevos”, con la advertencia de “usar esta opción solo si te sientes cómodo administrando bases de datos” (traducción propia). Súbelo a una carpeta con un nombre aleatorio, ejecuta la simulación, después el reemplazo, y borra la carpeta inmediatamente: cualquiera que la encuentre puede leer y reescribir la base de datos.

#5. Script PHP de buscar y reemplazar para datos serializados

Si necesitas el reemplazo dentro de tu propio código PHP (por ejemplo, en un proceso de despliegue sin WP-CLI), esta clase recorre de forma recursiva arrays y objetos, sustituye las cadenas y vuelve a serializar, de modo que el propio PHP recalcula los marcadores de longitud.

Créala como scripts/class-serialization-replace.php:

<?php
declare(strict_types=1);

namespace WPPoland\Database\Migrator;

class SerializationAwareReplacer {

    private string $search;
    private string $replace;

    public function __construct( string $search, string $replace ) {
        $this->search  = $search;
        $this->replace = $replace;
    }

    /**
     * Entry point to recursively search and replace strings in data.
     */
    public function process( $data ) {
        if ( is_string( $data ) ) {
            // Check if string is serialized
            if ( $this->is_serialized_string( $data ) ) {
                $unserialized = unserialize( $data );
                if ( false !== $unserialized ) {
                    return serialize( $this->process( $unserialized ) );
                }
            }
            return str_replace( $this->search, $this->replace, $data );
        }

        if ( is_array( $data ) ) {
            $cleaned = [];
            foreach ( $data as $key => $value ) {
                $cleaned[ $key ] = $this->process( $value );
            }
            return $cleaned;
        }

        if ( is_object( $data ) ) {
            $cleaned = clone $data;
            foreach ( get_object_vars( $data ) as $key => $value ) {
                $cleaned->$key = $this->process( $value );
            }
            return $cleaned;
        }

        return $data;
    }

    /**
     * Checks if a string is serialized.
     */
    private function is_serialized_string( string $string ): bool {
        $string = trim( $string );
        if ( 'N;' === $string ) {
            return true;
        }
        if ( strlen( $string ) < 4 ) {
            return false;
        }
        if ( ':' !== $string[1] ) {
            return false;
        }
        $last_char = substr( $string, -1 );
        if ( ';' !== $last_char && '}' !== $last_char ) {
            return false;
        }
        $token = $string[0];
        switch ( $token ) {
            case 's':
                if ( '"' !== substr( $string, -2, 1 ) ) {
                    return false;
                }
                return true;
            case 'a':
            case 'O':
                return (bool) preg_match( "/^{$token}:[0-9]+:/s", $string );
            case 'b':
            case 'i':
            case 'd':
                return (bool) preg_match( "/^{$token}:[0-9.E-]+;\$/", $string );
        }
        return false;
    }
}

get_object_vars() llamada desde fuera de la clase solo ve las propiedades públicas, así que las propiedades privadas y protegidas de los objetos pasan sin cambios. Dentro de WordPress, las funciones del núcleo is_serialized() y maybe_unserialize() se encargan de la detección; WP-CLI sigue siendo la opción probada.

#6. Redirigir el dominio antiguo con reglas 301

La documentación de Google sobre traslados de sitios con cambios de URL pide redirecciones permanentes en el servidor, “como 301 y 308” (traducción propia), desde cada URL antigua hasta su equivalente nueva. Su documentación sobre redirecciones explica que, con estos códigos permanentes, “el proceso de indexación usa la redirección como señal de que el destino de la redirección debe ser canónico” (traducción propia); los códigos temporales (302, 303, 307) no envían esa señal.

#Redirección 301 en Nginx que conserva la URI de la petición

Conserva la ruta y la cadena de consulta con $request_uri. La guía de Google sobre traslados desaconseja enviar muchas URL antiguas a una sola página sin relación, como la nueva portada; la regla de abajo produce una correspondencia de página a página:

server {
    listen 80;
    listen 443 ssl;
    server_name old-domain.com www.old-domain.com;

    # ssl_certificate y ssl_certificate_key del dominio antiguo van aquí

    # Redirección permanente que conserva la ruta y la cadena de consulta
    return 301 https://new-domain.com$request_uri;
}

El dominio antiguo sigue necesitando un certificado válido: una petición HTTPS a ese dominio falla durante el intercambio TLS antes de que Nginx pueda enviar la redirección.

#Redirección 301 en .htaccess de Apache a un dominio nuevo

Añade estas reglas al principio del archivo .htaccess del dominio antiguo (más patrones en nuestra lista de redirecciones en .htaccess):

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteCond %{HTTP_HOST} ^(?:www\.)?old-domain\.com$ [NC]
  RewriteRule ^(.*)$ https://new-domain.com/$1 [R=301,L]
</IfModule>

mod_rewrite añade por defecto la cadena de consulta original al destino, así que ?page=2 sobrevive a la redirección.

#Redirección con un Cloudflare Worker en el edge

Si el dominio antiguo pasa por el proxy de Cloudflare, un Worker puede responder con la redirección sin llegar al servidor de origen. El código sigue la sintaxis de módulos del ejemplo de redirección de la propia Cloudflare:

export default {
  async fetch(request) {
    const base = "https://new-domain.com";
    const { pathname, search } = new URL(request.url);
    return Response.redirect(`${base}${pathname}${search}`, 301);
  },
};

#7. Lista de comprobación SEO de la migración y configuración de Google Search Console

#Cómo usar la herramienta de cambio de dirección de Search Console

La página de ayuda de la herramienta de cambio de dirección de Google fija estas condiciones:

1. Propiedad: “debes ser propietario de las propiedades antigua y nueva en Search Console” (traducción propia).
2. Solo a nivel de dominio: la herramienta “solo se puede usar en propiedades a nivel de dominio” y “no traslada ningún subdominio por debajo del dominio indicado (incluido www)” (traducción propia). Envía solicitudes separadas para las variantes con www y sin www que estén en uso o se hayan usado en el pasado.
3. Primero la redirección: configura una redirección 301 de la portada antigua a la nueva y del resto de páginas. La herramienta comprueba que eres propietario de ambos sitios y que algunas páginas devuelven redirecciones 301.
4. Ejecución: abre la propiedad antigua, ve a Ajustes, elige Cambio de dirección y selecciona la propiedad nueva.
5. Sitemaps: envía el nuevo sitemap XML. La guía de Google sobre traslados indica que las advertencias por URL que redirigen en el sitemap antiguo son esperables mientras ambos estén enviados.

La herramienta no hace falta para pasar de HTTP a HTTPS, para cambiar entre www y sin www en el mismo dominio ni para cambios de ruta dentro de un mismo dominio.

#Qué más hay que actualizar en el dominio nuevo

La guía de traslados enumera los cambios en el propio sitio que acompañan a las redirecciones:

• Actualiza los enlaces internos para que apunten directamente a las URL nuevas, sin pasar por una redirección.
• Da a cada URL nueva una etiqueta canonical que apunte a sí misma.
• Si usas hreflang, “asegúrate de actualizar las anotaciones para que usen las URL nuevas” (traducción propia).
• Comprueba que el robots.txt del dominio nuevo no conserva el Disallow: / de staging.

#8. Cuánto tiempo mantener las redirecciones tras cambiar el dominio de WordPress

Google da dos cifras. La página de ayuda del cambio de dirección dice que el traspaso de señales continúa “durante 180 días después de iniciar la migración en Search Console” y pide mantener las redirecciones al menos 180 días, “más tiempo si sigues viendo tráfico hacia ellas desde la Búsqueda de Google” (traducción propia). La guía de traslados va más allá: mantén las redirecciones todo el tiempo que puedas, en general al menos un año. Renovar el registro del dominio antiguo forma parte de ello, porque las redirecciones dejan de funcionar el día en que caduca el dominio.

En cuanto a los plazos, la misma guía indica que un sitio de tamaño medio “puede tardar unas semanas o más” (traducción propia) hasta que Google muestra poco a poco las URL nuevas, y los sitios más grandes tardan más. Las fluctuaciones de posiciones en ese periodo son normales, así que evalúa el traslado con los datos de Search Console a lo largo de semanas, no de días.

#9. Por qué WordPress sigue redirigiendo al dominio antiguo tras la migración

Si después del reemplazo el sitio te sigue enviando a la dirección antigua, revisa estos puntos en orden:

• wp-config.php: una constante WP_HOME o WP_SITEURL olvidada con el valor antiguo sobrescribe la base de datos.
• wp_options: ejecuta wp option get home y wp option get siteurl, o consulta las dos filas en phpMyAdmin.
• .htaccess y configuración del servidor: algunos plugins de seguridad y de redirecciones escriben ahí sus reglas, y puede seguir existiendo un bloque server antiguo.
• Cachés: la caché de página, la caché de objetos (wp cache flush), una CDN y la propia caché del navegador con una 301 anterior pueden servir el destino antiguo.

#10. Lista de comprobación para cambiar el dominio de WordPress

Usa esta lista en tus migraciones de dominio en WordPress:

• Haz una copia de seguridad de la base de datos y de todo el sistema de archivos, incluido wp-content/uploads.
• Guarda una lista de las URL actuales del sitio para construir y comprobar el mapa de redirecciones.
• Configura el alojamiento nuevo e instala los certificados SSL del dominio nuevo, y mantén un certificado válido en el antiguo.
• Importa la base de datos y actualiza las credenciales en wp-config.php.
• Ejecuta wp search-replace con --dry-run y --skip-columns=guid y revisa el informe.
• Ejecuta el reemplazo para las variantes HTTPS y HTTP.
• Elimina las líneas temporales WP_HOME, WP_SITEURL o RELOCATE que ya no hagan falta.
• Vacía las reglas de reescritura y las cachés, y comprueba home y siteurl.
• Comprueba que las imágenes cargan desde el dominio nuevo, que los formularios envían y, si tienes WooCommerce, que el proceso de pago funciona.
• Configura redirecciones 301 de página a página en el dominio antiguo.
• Actualiza las etiquetas canonical, las anotaciones hreflang y los enlaces internos.
• Envía el cambio de dirección en Search Console y el nuevo sitemap.
• Mantén las redirecciones y el registro del dominio antiguo al menos un año.

¿Necesitas ayuda para migrar la base de datos de WordPress o configurar reglas de redirección en el servidor? Nuestro equipo de desarrollo WordPress puede auditar la base de datos, ejecutar la migración y configurar Search Console. Contáctanos para hablar de tu proyecto.