Usted instala un plugin y este arrastra su propia copia de jQuery. Su tema ya cargó jQuery mediante wp_enqueue_script. El plugin, una vez más, lo carga directamente desde una CDN. En la página: dos o incluso tres versiones de la misma librería. Conflictos, tamaño inflado, comportamiento impredecible.

El problema es tan antiguo como el propio WordPress, pero sigue ocurriendo: los desarrolladores copian y pegan <script src="jquery.js"> en header.php «porque es más rápido». Más rápido, hasta el primer conflicto con un plugin que espera la versión nativa de WP.

A partir de 2026, WordPress incluye jQuery 3.6.0 de serie y proporciona una forma simple y determinista de incluirlo sin duplicaciones y sin rastrear versiones manualmente. A continuación se presenta el único enfoque correcto, desde el wp_enqueue_script básico hasta reemplazarlo de forma segura con una versión CDN y usar el modo noConflict.

💡 Resumen rápido:

• Cómo WordPress ya carga jQuery y por qué no debería hacerlo manualmente
• wp_enqueue_script con la dependencia jquery: una línea en functions.php
• Cuándo y cómo reemplazar de forma segura el jQuery integrado con una versión CDN (Google / cdnjs)
• Modo noConflict: protección contra colisiones con otras librerías
• Consejos para temas y plugins: cuándo NO debe sobrescribir el jQuery integrado

JQuery ya está en el núcleo: lo que WordPress hace por usted

A partir de la versión 3.6, WordPress registra jQuery bajo el identificador jquery. Usted no necesita descargar jquery.min.js, colocarlo en la carpeta de su tema e incluirlo con una etiqueta <script>. El núcleo hace esto automáticamente tan pronto como usted especifica jquery en las dependencias de su script.

La versión actual de jQuery en el núcleo de WordPress es la 3.6.0. Viene empaquetada con jQuery Migrate (para compatibilidad con código heredado) y se carga solo cuando algún script declara jquery como dependencia. Sin dependencias, jQuery no aparece en la página y el sitio no carga recursos innecesarios.

Por eso un <script src="/wp-content/themes/mytime/jquery.js"> directo en header.php es un error, no un atajo. Usted elude el sistema de dependencias, elimina la capacidad de WP para gestionar el orden de carga y obtiene un duplicado cuando un plugin solicita legítimamente jquery mediante wp_enqueue_script.

La forma correcta: wp_enqueue_script con una dependencia

La mecánica básica cabe en una línea dentro del hook wp_enqueue_scripts. Usted escribe su script y WordPress determina cuándo y en qué orden cargar todo.

Cree (o abra) el functions.php de su tema y añada:

1
function mytheme_enqueue_scripts() {
2
    wp_enqueue_script(
3
        'mytheme-main',
4
        get_template_directory_uri() . '/js/main.js',
5
        array( 'jquery' ),
6
        '1.0.0',
7
        array(
8
            'strategy'  => 'defer',
9
            'in_footer' => true,
10
        )
11
    );
12
}
13
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Lo que está sucediendo aquí:

• mytheme-main es el identificador único para su script. Invente el suyo propio, con el prefijo del nombre del tema.
• get_template_directory_uri() . '/js/main.js' es la ruta al archivo. También puede usar una URL de CDN externa.
• array( 'jquery' ) es el punto clave: le está diciendo a WP «mi script depende de jQuery». El núcleo ve esto y automáticamente pone en cola jQuery antes de su script. Sin etiquetas <script> en la plantilla.
• '1.0.0' es la versión para la invalidación de caché. Cámbiela con cada actualización del script.
• array( 'strategy' => 'defer', 'in_footer' => true ): desde WordPress 6.3, el parámetro $args acepta un array. defer significa «ejecutar el script después de que el DOM esté construido pero antes de DOMContentLoaded». in_footer coloca el script en el pie de página.

La sintaxis antigua con un quinto parámetro booleano (true = en el pie de página) todavía funciona, pero para proyectos nuevos use la sintaxis de array. Es más legible y le da control sobre async/defer.

Verifique que su tema llame a wp_head() antes del cierre de </head> y a wp_footer() antes de </body>. Sin estas llamadas, wp_enqueue_script simplemente no funcionará. Esta es una trampa común al migrar desde temas antiguos.

Cómo reemplazar el jQuery integrado con su propia versión

A veces la versión nativa no es suficiente. Usted quiere jQuery 4.0.0 desde una CDN por las últimas correcciones, o necesita una versión específica para compatibilidad con un plugin heredado. Puede reemplazarla, pero con cuidado.

El error: simplemente llamar a wp_enqueue_script('jquery', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'). WordPress NO sobrescribe un identificador ya registrado. Obtendrá tanto la versión nativa como la versión CDN en la misma página.

La secuencia correcta: primero desregistre el jquery nativo, luego registre el suyo:

1
function mytheme_use_cdn_jquery() {
2
    // Deregister the built-in jQuery
3
    wp_deregister_script( 'jquery' );
4
 
5
    // Register your own — from CDN
6
    wp_register_script(
7
        'jquery',
8
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js',
9
        array(),
10
        '4.0.0',
11
        true
12
    );
13
 
14
    // Enqueue it
15
    wp_enqueue_script( 'jquery' );
16
}
17
add_action( 'wp_enqueue_scripts', 'mytheme_use_cdn_jquery' );

Tres puntos que a menudo se pasan por alto:

Google Hosted Libraries. La CDN alternativa de Google sigue activa y aloja jQuery 3.7.1: https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js. La ventaja: millones de sitios ya tienen calientes las cachés del navegador para esta URL. La desventaja: Google añade sus propias cabeceras y no actualiza las versiones inmediatamente después del lanzamiento.

cdnjs. Si necesita jQuery 4.0.0, obténgalo de cdn.jsdelivr.net/npm/[email protected]/. cdnjs replica el paquete npm y lo sirve con las cabeceras CORS adecuadas.

No desregistre jQuery en temas públicos. Si su tema va al repositorio de WordPress.org, use el jQuery nativo del núcleo. La razón es simple: cuando un sitio tiene tanto un tema (con jQuery 4.0.0 de CDN) como un plugin (que espera jQuery 3.6.0 del núcleo), el usuario resuelve el conflicto, no el desarrollador. En temas comerciales y proyectos a medida, siéntase libre de reemplazarlo.

Modo noConflict: cuando hay más de una librería en la página

Por defecto, jQuery ocupa la variable global $. El problema es que $ es un nombre popular: Prototype, MooTools y algunos frameworks heredados también lo usan. Si un plugin u otro script también reclama $, el que se cargó último gana y los demás se rompen.

Protección en una línea al inicio de su script:

1
var $j = jQuery.noConflict();

Después de esto, $ queda liberado para otras librerías y su código funciona a través de $j. Ejemplo completo: una barra lateral con animación hover:

1
jQuery(document).ready( function( $ ) {
2
    // Here $ is jQuery, but only inside this function
3
    $( '#sidebar li a' ).hover(
4
        function() {
5
            $( this ).stop().animate( { paddingLeft: '20px' }, 400 );
6
        },
7
        function() {
8
            $( this ).stop().animate( { paddingLeft: '0' }, 400 );
9
        }
10
    );
11
} );

Aquí $ funciona como jQuery dentro de la clausura jQuery(document).ready(), y fuera está libre para otros. Esto es más limpio que generar variables $j, $jq y $myJQ por todo su código.

Cuándo noConflict no es necesario: si su sitio funciona completamente con WordPress sin frameworks JS de terceros y todos los plugins están escritos para wp_enqueue_script, $ es seguro. Pero incluir noConflict en el código base estándar de su tema es un buen hábito que cuesta solo una línea.

Lo que los desarrolladores de plugins deben hacer

Si está escribiendo un plugin para distribución pública, use solo wp_enqueue_script con una dependencia de jquery. Nada de wp_deregister_script('jquery') dentro de los plugins: usted no sabe qué versión de jQuery esperan otros plugins en el mismo sitio.

El patrón correcto para un plugin se ve así:

1
function myplugin_frontend_scripts() {
2
    wp_enqueue_script(
3
        'myplugin-frontend',
4
        plugins_url( '/js/frontend.js', __FILE__ ),
5
        array( 'jquery' ),
6
        MYPLUGIN_VERSION,
7
        true
8
    );
9
}
10
add_action( 'wp_enqueue_scripts', 'myplugin_frontend_scripts' );

MYPLUGIN_VERSION es la constante de versión del plugin. Con cada actualización del plugin, el navegador del usuario obtiene un script nuevo en lugar de uno antiguo en caché.

Para scripts de administración (solo panel de administración), use el hook admin_enqueue_scripts. jQuery en el panel de administración también está registrado bajo el mismo identificador jquery.

⁉️🤔 Preguntas frecuentes

¿Por qué no funciona mi código jQuery aunque wp_enqueue_script se llama correctamente?

La causa más común: el tema no llama a wp_head() y wp_footer(). Sin estas funciones, WordPress físicamente no puede insertar etiquetas <script> en el HTML. Abra header.php. Debería haber <?php wp_head(); ?> antes de </head>. En footer.php, debería haber <?php wp_footer(); ?> antes de </body>. Si el tema es antiguo y faltan estas llamadas, añádalas. Esto es seguro. Todos los temas y plugins modernos dependen de wp_head/wp_footer. Sin ellas, no solo se rompe la carga de scripts, sino también los plugins de SEO, las fuentes y los datos estructurados.

¿Puedo usar jQuery 4.0.0 en WordPress si el núcleo viene con 3.6.0?

Sí, mediante wp_deregister_script + wp_register_script (vea la sección anterior). Pero note: jQuery 4.0.0 eliminó el soporte para IE 11 y varios métodos obsoletos. Si su sitio o plugin depende de jQuery Migrate, quédese con la versión del núcleo o incluya Migrate explícitamente. WordPress está migrando gradualmente hacia JavaScript nativo y React para el editor de bloques, pero jQuery permanecerá en el núcleo por mucho tiempo: demasiados temas y plugins dependen de él.

Un plugin carga su propio jQuery aunque yo ya lo incluí mediante functions.php. ¿Qué debo hacer?

El plugin probablemente codificó de forma fija <script src="jquery..."> eludiendo wp_enqueue_script. Esto es un error del plugin. Dos soluciones: encuentre la llamada directa en el código del plugin y reemplácela con wp_enqueue_script con una dependencia (si está dispuesto a parchear el plugin), o contacte al autor del plugin pidiéndole que lo corrija. Como solución temporal, puede llamar a wp_dequeue_script o eliminar el hook del plugin, pero esto trata los síntomas en lugar de la causa.

¿Qué es más rápido: jQuery del núcleo de WordPress o de una CDN?

Si el navegador del usuario ya almacenó en caché jQuery desde una CDN (Google o cdnjs), la versión CDN se carga instantáneamente con un código 304 No modificado. Si no, la diferencia de velocidad de carga entre el núcleo y la CDN es insignificante para jQuery (aproximadamente 85 KB comprimidos). Para proyectos de alto tráfico, una CDN ahorra el ancho de banda de su servidor; para un sitio WordPress típico, no hay diferencia.

¿Debería abandonar jQuery en favor de JS nativo?

Respuesta corta: depende del proyecto. jQuery 4.0.0 comprimido pesa unos 85 KB. Eso no es cero, pero tampoco es motivo de pánico. El JS nativo moderno (querySelectorAll, fetch y classList) cubre el 90% de lo que la gente necesitaba de jQuery en 2015. Si está construyendo un tema nuevo desde cero y no depende de plugins de jQuery, considere vanilla JS. Es más limpio y rápido.

Pero si el proyecto ya tiene dependencias de jQuery (sliders, galerías, componentes de interfaz de plugins), no complique las cosas. WordPress cargará jQuery de todos modos cuando un plugin lo solicite. Escriba llamadas limpias a wp_enqueue_script con dependencias, no interfiera en la gestión del orden de carga del núcleo y jQuery funcionará rápido y de forma predecible.

🔗 Documentación de wp_enqueue_script | 🔗 Documentación de wp_deregister_script