Los mapas de origen son una herramienta fundamental en el desarrollo web moderno que facilitan la depuración mucho más fácil. En esta página, se exploran los conceptos básicos de los mapas de fuentes, su funcionamiento generados y cómo mejoran la experiencia de depuración.
La necesidad de los mapas de origen
Las primeras aplicaciones web se compilaban con una complejidad baja. Los desarrolladores implementaron HTML, CSS, y archivos JavaScript directamente a la Web.
Las aplicaciones web más modernas y complejas pueden necesitar una variedad de herramientas en su en el flujo de trabajo de desarrollo de software. Por ejemplo:
- Lenguajes de plantillas y preprocesadores HTML: Pug, Nunjucks Markdown.
- Preprocesadores de CSS: SCSS, LESS y PostCSS.
- Frameworks de JavaScript: Angular, React Vue y Svelte.
- Metaframeworks de JavaScript: Next.js, Nuxt y Astro.
- Lenguajes de programación de alto nivel: TypeScript, Dart, CoffeeScript.
![Una breve descripción general de varias herramientas.](https://web.dev/static/articles/source-maps/image/a-brief-overview-various-769879995ff7c.png?authuser=9&hl=es)
Estas herramientas requieren un proceso de compilación para transpilar su código a HTML estándar, JavaScript y CSS que los navegadores puedan comprender. También es una práctica común optimizar el rendimiento mediante la reducción y la combinación de estos archivos con una herramienta como Terser.
Por ejemplo, usando herramientas de compilación, podemos transpilar y comprimir los siguientes TypeScript en una sola línea de JavaScript. Puedes probarlo tú mismo en esta demostración en GitHub.
/* A TypeScript demo: example.ts */
document.querySelector('button')?.addEventListener('click', () => {
const num: number = Math.floor(Math.random() * 101);
const greet: string = 'Hello';
(document.querySelector('p') as HTMLParagraphElement).innerText = `${greet}, you are no. ${num}!`;
console.log(num);
});
Una versión comprimida sería:
/* A compressed JavaScript version of the TypeScript demo: example.min.js */
document.querySelector("button")?.addEventListener("click",(()=>{const e=Math.floor(101*Math.random());document.querySelector("p").innerText=`Hello, you are no. ${e}!`,console.log(e)}));
Sin embargo, comprimir el código puede dificultar la depuración. Mapas de fuentes puedes quitar este problema: asignando de nuevo tu código compilado al código original, pueden ayudarte a encontrar rápidamente la fuente de un error.
Cómo generar mapas de orígenes
Los mapas de orígenes son archivos cuyos nombres terminan con .map
(por ejemplo,
example.min.js.map
y styles.css.map
). La mayoría de las compilaciones
herramientas, como Vite y webpack,
Rollup, Parcel y
esbuild.
Algunas herramientas incluyen mapas de orígenes de forma predeterminada. Otras pueden necesitar de Terraform para producirlos:
/* Example configuration: vite.config.js */
/* https://vitejs.dev/config/ */
export default defineConfig({
build: {
sourcemap: true, // enable production source maps
},
css: {
devSourcemap: true // enable CSS source maps during development
}
})
Comprende el mapa de fuentes
Para ayudar con la depuración, estos archivos del mapa de origen contienen información esencial sobre cómo se asigna el código compilado al código original. Aquí hay un ejemplo de un Mapa de orígenes:
{
"mappings": "AAAAA,SAASC,cAAc,WAAWC, ...",
"sources": ["src/script.ts"],
"sourcesContent": ["document.querySelector('button')..."],
"names": ["document","querySelector", ...],
"version": 3,
"file": "example.min.js.map"
}
Para comprender cada uno de estos campos, puedes leer la especificación del mapa de origen o Anatomía de un mapa de fuentes.
La parte más importante de un mapa de fuentes es el campo mappings
. Utiliza un
String codificada en base 64 de VLQ
para asignar líneas y ubicaciones del archivo compilado al original correspondiente
. Puedes ver esta asignación usando un visualizador de mapas de origen, como
source-map-visualization o
Visualización del mapa de origen.
![Visualización de un mapa de fuentes.](https://web.dev/static/articles/source-maps/image/a-source-map-visualizatio-4866bc351df59.png?authuser=9&hl=es)
En la columna generated de la izquierda, se muestra el contenido comprimido y las original muestra la fuente original.
El visualizador codifica por color cada línea de la columna original con su el código correspondiente en la columna generated.
En la sección mappings, se muestran las asignaciones decodificadas del código. Por ejemplo, el
la entrada 65 -> 2:2
significa lo siguiente:
- Código generado: La palabra
const
comienza en la posición 65 en el contenido comprimido. - Código original: La palabra
const
comienza en la línea 2 y en la columna 2 del contenido original.
![Entrada de asignación.](https://web.dev/static/articles/source-maps/image/mapping-entry-dc9df15808405.png?authuser=9&hl=es)
65 -> 2:2
.Esto permite a los desarrolladores identificar rápidamente la relación entre el código reducido y el código original, lo que simplifica la depuración.
Las herramientas para desarrolladores del navegador aplican estos mapas de origen para ayudarte a identificar tu depurar errores rápidamente en el navegador.
![Herramientas para desarrolladores que aplican un mapa de fuentes](https://web.dev/static/articles/source-maps/image/developer-tools-applies-ea66f57e838eb.png?authuser=9&hl=es)
Extensiones de mapas de fuentes
Los mapas de orígenes admiten campos de extensión personalizados que comienzan con un prefijo x_
. Uno
Un ejemplo es el campo de extensión x_google_ignoreList
propuesto por Chrome
Herramientas para desarrolladores. Ver x_google_ignoreList
para obtener más información sobre cómo estas extensiones te ayudan a enfocarte en tu código.
Desventajas del mapa de fuentes
Desafortunadamente, las asignaciones de fuentes no siempre son tan completas como necesitas que lo sean.
En nuestro primer ejemplo, la variable greet
se optimizó durante la compilación
proceso, a pesar de que su valor está directamente incorporado en la salida final de la cadena.
![No se asignó la variable greet.](https://web.dev/static/articles/source-maps/image/variaqble-greet-is-map-a93a440f3c171.png?authuser=9&hl=es)
greet
del original
si falta código en la asignación.En este caso, cuando depures el código, es posible que las herramientas para desarrolladores no puedan inferirás y mostrarás el valor real. Este tipo de error puede hacer que tu código la supervisión y el análisis de datos.
![La variable greet no está definida.](https://web.dev/static/articles/source-maps/image/variable-greet-is-undefin-19fcbf9a06a26.png?authuser=9&hl=es)
greet
.Este es un problema que debe resolverse en el diseño de los mapas de origen. Uno la posible solución es incluir información del alcance en los mapas de origen de la del mismo modo que lo hacen otros lenguajes de programación con su información de depuración.
Sin embargo, esto requiere que todo el ecosistema trabaje en conjunto la especificación y la implementación del mapa de fuentes. Para seguir el proceso para mejorar la depuración con mapas de fuentes, consulta la propuesta de Mapas de origen v4 en GitHub.