Se ha cambiado el nombre de dominio del HTML exportado. ¿Por qué están rotas las imágenes y los enlaces?

El punto de referencia de urljoin debe ser la URL de la página original. No puede agregar barras para cambiar la URL del archivo a un directorio. Este ejemplo solo maneja a[href] e img[src] y no anula las etiquetas CSS, srcset o base; Reescribir URL no es una desinfección segura de HTML.

Después de que el HTML exportado se migra a un nuevo nombre de dominio, las imágenes y los enlaces dejan de ser válidos. Este es un problema que muchos equipos encuentran al organizar documentos, wikis o sitios antiguos. Este tipo de problema a menudo no es que el recurso realmente se pierda, sino que la ruta relativa pierde su contexto de análisis original.

Este artículo es adecuado para desarrolladores e ingenieros de documentación responsables de migraciones de sitios, exportaciones estáticas o reescritura de enlaces por lotes. Después de leer, podrá juzgar qué enlaces deben reescribirse, cuáles deben conservarse y saber en qué escenarios los scripts automatizados no pueden reemplazar la aceptación manual.

Los ejemplos siguientes son solo demostraciones didácticas y no pueden utilizarse directamente como soluciones a nivel de producción. Su alcance y límites de verificación también se explicarán en el texto.

¿Por qué las imágenes y los enlaces se rompen después de la migración? Conclusión de una frase

Las imágenes y enlaces no válidos suelen deberse a la pérdida del contexto de análisis. Al reescribir, se debe utilizar la URL de la página original como base y solo se deben procesar atributos explícitos.

tu situaciónPrácticas recomendadasrazón
URL de la página del archivoMantener la línea base originalNo agregue ciegamente una barra diagonal; de lo contrario, la URL del archivo se cambiará a un directorio
Requiere procesamiento de etiquetas CSS, srcset o baseEste ejemplo no cubre esto y debe manejarse por separado.El ejemplo solo maneja a[href] y img[src]
ancla de fragmentoMantenga esta página referenciadaNo fuerce el cambio a la página remota
Enlace con protocolo de scriptEliminar este atributo del ejemplo.Reescribir la URL no equivale a limpiar la seguridad de HTML. El HTML completo todavía necesita ser desinfectado de forma segura.
Enlaces o referencias generados por JavaScript dentro de Shadow DOMAceptación en un entorno de navegador realBeautifulSoup no puede tocar este contenido.

¿Por qué falla la ruta relativa?

Analizar el contexto de dependencia

Cuando las empresas migran documentos internos, wikis o sitios heredados a un nuevo nombre de dominio, son comunes las imágenes rotas y los redireccionamientos de enlaces incorrectos. Por lo general, esto no es una pérdida de recursos, sino una pérdida de contexto de análisis.

Cuando los navegadores resuelven rutas relativas (como images/logo.png), siguen el estándar RFC 3986:

  • Busque primero las etiquetas <base href="...">.
  • Si <base> no está presente, se calcula en función de la URL del documento actual.

Si el HTML estático exportado no se inyecta con la etiqueta <base> correcta ni se desvía de la estructura del directorio original, todas las referencias relativas apuntarán al directorio raíz del nuevo nombre de dominio o a la ruta de la página actual, lo que dará como resultado el recurso 404.

Diferencias semánticas entre etiquetas urljoin y base

Comportamiento predeterminado de urljoin

urllib.parse.urljoin(base, url) es la herramienta principal que maneja la reescritura de enlaces, pero existen diferencias sutiles en cómo los navegadores interpretan la etiqueta <base>. Muchos scripts que "arreglan y rompen" a menudo surgen de esto.

  • urljoin por defecto es base como "ruta de archivo" a menos que termine con /.
  • Por ejemplo, urljoin("https://new.com/docs", "img.png") da como resultado https://new.com/img.png (los documentos se descartan como nombres de archivos), no https://new.com/docs/img.png como se esperaba.

Estandarización de URL base

La etiqueta HTML <base> también se basa en barras diagonales para distinguir archivos y directorios en los navegadores, pero tiene una tolerancia a errores ligeramente mayor para entradas no estándar. En el procesamiento programático, no se puede asumir que la entrada tenga ciertas especificaciones, por lo que se debe realizar un preprocesamiento antes de llamar a urljoin:

  1. Compruebe si el plan es legal.
  2. Agregue el sufijo / al dato confirmado como directorio. Las URL de las páginas de archivos deben conservar su base original.
  3. Filtre los valores nulos.

Sólo las URL base estandarizadas se pueden utilizar como entrada confiable.

Ruta absoluta y enlace completo.

Para rutas absolutas que comienzan con /, o enlaces que contienen el protocolo completo, urljoin devuelve el valor original directamente o reemplaza solo el nombre de host. Esta característica la hace más segura que la concatenación de cadenas, pero también requiere que los desarrolladores distingan claramente entre "reescribir" y "preservar" los límites.

Ejemplos de síntesis y condiciones de contorno.

El siguiente código muestra cómo reescribir de forma segura enlaces de recursos en HTML. Nota: Este es un ejemplo de tutorial sintético, el propósito es demostrar la lógica, no proporcionar una implementación a nivel de producción. El ejemplo utiliza cadenas en memoria para simular la entrada, evitando operaciones del sistema de archivos y solicitudes de red. El código se ha verificado con datos de muestra en un entorno aislado, pero esto no significa que funcionará en todos los archivos reales; verifíquelo usted mismo en un entorno controlado.

from urllib.parse import urljoin, urlsplit
from bs4 import BeautifulSoup
def rewrite(markup, page_url):
    soup = BeautifulSoup(markup, "html.parser")
    for tag, attr in [("a", "href"), ("img", "src")]:
        for node in soup.find_all(tag):
            value = node.get(attr)
            if not value or value.startswith("#"):
                continue
            result = urljoin(page_url, value)
            if urlsplit(result).scheme not in {"https", "http"}:
                del node[attr]
            else:
                node[attr] = result
    return soup
result = rewrite('<img src="logo.png"><a href="../guide/">Guide</a><a href="#top">Top</a><a href="javascript:alert(1)">Bad</a>', "https://example.com/docs/page.html")
assert result.img["src"] == "https://example.com/docs/logo.png"
assert result.find_all("a")[0]["href"] == "https://example.com/guide/"
assert result.find_all("a")[1]["href"] == "#top"
assert "href" not in result.find_all("a")[2].attrs

Criterios de aceptación y límites de revisión manual

Los scripts automatizados pueden solucionar problemas de empalme de rutas mecánicas, pero no pueden reemplazar el juicio sobre la semántica empresarial. La siguiente tabla enumera excepciones comunes y decisiones de manejo para ayudar al equipo a distinguir entre escenarios "resolubles por código" y "que requieren intervención manual".

No aplicable: este método solo se aplica a la reescritura de atributos HTML estáticos. BeautifulSoup no puede tocar enlaces generados por el tiempo de ejecución de JavaScript, referencias dentro de Shadow DOM, URL en CSS background-image o rutas de textura de Canvas/WebGL. Estas situaciones requieren aceptación en un entorno de navegador real o pruebas de regresión visual de un extremo a otro utilizando Playwright o Puppeteer. La demostración del código no equivale a la calidad de la entrega y la aceptación debe basarse en los resultados de la representación del agente de usuario.

Próximos pasos recomendados

  • Agregar verificación de aserciones después de reescribir el enlace a la canalización de CI/CD.
  • Muestreo de documentos históricos de exportación para verificar la accesibilidad de los recursos.
  • Si a menudo encuentra problemas de vinculación de contenido dinámico, evalúe la necesidad de introducir un navegador sin cabeza para realizar pruebas de regresión visual.

Cualquier corrección automatizada debe considerarse una ayuda y no un reemplazo de la revisión manual.

📊 Comparación central

Formulario de entradaCómo manejar la unión de URLPuntos a tener en cuenta
Puntos de referencia que no terminan en / (como docs)El último párrafo se descarta como nombre de archivo.El resultado puede ser https://new.com/img.png (docs se descarta como nombre de archivo) en lugar de la ruta al directorio esperado
Camino absoluto que comienza con /Devuelve el valor original directamente o reemplaza solo el nombre del hostMás seguro que la concatenación de cadenas
Enlace al acuerdo completoDevuelve el valor original directamente o reemplaza solo el nombre del hostEs necesario distinguir claramente los límites entre reescritura y retención.

🎯 ¿Qué método es el adecuado para ti?

si usted……

  • Para migrar HTML exportado estáticamente: primero confirme si la URL base de cada página es un archivo o directorio y luego decida si desea agregar una barra diagonal.
  • Solo es necesario manejar a[href] y img[src]: puede consultar el ejemplo en este artículo, pero recuerde que CSS, srcset y <base> no están cubiertos.
  • La página depende en gran medida de JavaScript: no confíe solo en la reescritura estática, debe representar la aceptación en un navegador real.
  • Es necesario garantizar la seguridad de la página: la reescritura de URL no es igual a la purificación de la seguridad HTML y el contenido riesgoso, como los scripts, también debe procesarse por separado.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué urljoin descarta el último segmento de la ruta del directorio?

Debido a que urljoin por defecto es base que no termina con / como ruta de archivo, el último segmento se descartará como nombre de archivo. Por ejemplo, el resultado de urljoin("https://new.com/docs", "img.png") es https://new.com/img.png (docs se descarta como nombre de archivo).

2. ¿Puedes agregar directamente una barra diagonal a todas las URL base?

No recomendado. Agregar barras diagonales juzgará erróneamente la URL de la página de tipo de archivo como un directorio, lo que generará resultados de análisis incorrectos para rutas relativas. Primero debe determinar si la referencia es un archivo o un directorio, y solo agregar barras a la referencia que se confirma que es un directorio.

3. Después de reescribir la URL, ¿es seguro HTML?

No. La reescritura de URL no equivale a la desinfección de la seguridad de HTML. El atributo del protocolo de secuencia de comandos se elimina en el ejemplo, pero la seguridad del HTML completo aún debe tratarse por separado.

4. ¿Qué enlaces no pueden repararse con este script?

Los enlaces generados por el tiempo de ejecución de JavaScript, las referencias dentro de Shadow DOM, las URL en CSS background-image y las rutas de textura de Canvas o WebGL no se pueden anular mediante anulaciones de atributos HTML estáticos y requieren aceptación en un entorno de navegador real.

Referencias

-Documentación oficial de Beautiful Soup - Atributos

📝 Resumen

Al exportar HTML y cambiar nombres de dominio, las imágenes y los enlaces dejan de ser válidos. La clave está en el análisis comparativo de trayectorias relativas. Al utilizar la URL de la página original como base, estandarizar y aclarar la cobertura del guión, puede mantener los problemas dentro de límites aceptables.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original

Actualizado 2026-11-15