Forja WP Audit: encuentra imágenes duplicadas y rotas en tu WordPress

Una biblioteca de medios de WordPress con cinco años no se ordena: se acumula. La misma foto del equipo subida tres veces con tres nombres. Un banner que apunta al dominio de la web anterior. Una imagen borrada hace dos años que sigue rota en cuarenta posts.

Nadie lo ve hasta que toca migrar, rediseñar o averiguar por qué la web pesa tanto. Para eso he publicado [Forja WP Audit](https://github.com/ivanqv/Forja-WP-Audit "follow"): una herramienta de código abierto (licencia MIT) que audita las imágenes de un WordPress desde fuera. No hace falta plugin, ni acceso a la base de datos, ni tocar la web.

Tres cosas que cualquier WordPress con años acumula y que el panel no enseña:

• Imágenes duplicadas. banner.jpg, banner-1.jpg, banner-final.jpg. El mismo fichero, varias veces, con nombres distintos.
• Imágenes rotas. Ficheros que ya no existen y que siguen enlazados desde posts y páginas publicados.
• Dependencias de otros dominios. Imágenes que se cargan desde el dominio antiguo, desde el entorno de pruebas o desde la web de un tercero. El día que ese dominio caduque, se rompen solas.

Cada una tiene su opción. Se pueden combinar y la herramienta no descarga dos veces la misma imagen.

Usa la REST API pública de WordPress, la misma que consulta cualquier navegador. No necesita usuario ni contraseña:

1. Localiza la API (/wp-json/, y si no responde, ?rest_route=).
2. Recorre todos los posts y páginas publicados, de cien en cien y con dos peticiones a la vez como máximo, para no castigar el servidor.
3. Saca cada imagen del HTML: src, srcset, <picture>, los atributos de carga diferida (data-src, data-srcset) y la imagen destacada.
4. Normaliza las URLs y apunta en qué post o página aparece cada una.

El resultado es un inventory.json con todo el inventario y, con --html, un informe visual en un solo fichero que se abre en cualquier navegador sin conexión.

Con --duplicates descarga cada imagen una sola vez y calcula su SHA-256. Dos ficheros con el mismo hash son idénticos byte a byte, se llamen como se llamen. Eso es un duplicado confirmado.

Aparte, y marcado como candidato a revisar, agrupa los nombres que parecen subidas repetidas (foto.jpg, foto-1.jpg, foto-final.jpg). El nombre no prueba nada, así que el informe nunca lo mezcla con lo confirmado.

La parte que más cuesta hacer bien son los tamaños que genera WordPress. hero-300x200.jpg y hero-1024x683.jpg no son duplicados de hero.jpg: son las versiones responsive que crea WordPress al subirla. La herramienta las reconoce y no las cuenta. Sin esa regla, cualquier web normal saldría con cientos de «duplicados» falsos.

Del espacio que se podría recuperar da una estimación teórica. Desde fuera no se puede demostrar que dos URLs sean dos ficheros distintos en el disco, y el informe lo dice tal cual en lugar de prometer megas.

Con --health comprueba cada imagen con una petición ligera (HEAD), sin descargarla. Y no todo fallo es una «imagen rota»:

La diferencia importa. Un 404 se arregla. Un 403 puede ser tu propio plugin de seguridad bloqueando al auditor, y «arreglarlo» borrando la imagen sería un error. Para cada imagen que falla, el informe dice qué posts y páginas la usan, que es lo que hay que ir a corregir.

Cada dominio desde el que se sirven imágenes entra en una de tres categorías:

• Interno: el dominio de la web, con y sin www.
• Permitido: los que declaras con --allowed-domains, como tu CDN.
• Externo: todo lo demás.

Externo no significa error. Puede ser un servicio legítimo. Pero también puede ser staging.agencia-anterior.com, el dominio viejo de antes del cambio de marca o la web de otro que un día borra la foto. En una migración eso es lo primero que se pierde, y sin un inventario nadie lo detecta hasta que el cliente lo ve roto.

Está en desarrollo temprano y todavía no está en npm, así que se ejecuta desde el código. Hace falta Node.js 22 o superior y pnpm:

git clone https://github.com/ivanqv/Forja-WP-Audit.git
cd Forja-WP-Audit
pnpm install
pnpm dev audit https://tu-web.com --duplicates --health --html

Al terminar tienes reports/inventory.json y reports/report.html. Si tus imágenes salen de un CDN, añádelo con --allowed-domains cdn.tu-web.com para que no aparezca como externo.

Dos avisos:

• No borra nada. Es de solo lectura. Una imagen idéntica en dos rutas puede estar ahí a propósito o tener enlaces externos apuntándole. Cada resultado es información para que la revise una persona.
• Pregunta antes de auditar una web ajena. Solo hace peticiones públicas y con poca concurrencia, pero sigue siendo tráfico contra un servidor que no es tuyo.

La importación de WordPress de Forja trae entradas, medios y redirecciones 301, y avisa de lo que no sabe convertir. Pero una migración hereda la biblioteca tal y como está: si en origen hay tres copias del banner, la web nueva tiene tres copias. Si hay cuarenta imágenes rotas, siguen rotas.

Forja WP Audit es el paso de antes. Sirve para saber qué hay, decidir qué se queda y enseñárselo al cliente antes de mover nada. Lo he publicado abierto porque ese problema no es solo de quien migra a Forja. Lo tiene cualquiera que mantenga un WordPress, se quede donde se quede.

Además, las imágenes son muchas veces por qué la web va lenta, y parte de lo que cuesta de verdad mantener un WordPress es precisamente este tipo de limpieza que nadie presupuesta.

• Audita las imágenes de un WordPress desde fuera, por la REST API pública, sin plugin ni acceso a la base de datos.
• Detecta duplicados exactos por hash y separa los candidatos por nombre, que solo son para revisar.
• Reconoce los tamaños responsive de WordPress y no los cuenta como duplicados.
• Distingue una imagen rota de verdad (404) de una que solo no se deja ver (403, cortafuegos).
• Señala las imágenes servidas desde otros dominios: el antiguo, staging o terceros.
• Es de solo lectura, con licencia MIT, y está en [GitHub](https://github.com/ivanqv/Forja-WP-Audit "follow").