Co to są mapy źródeł?

Mapy źródeł to kluczowe narzędzie w nowoczesnym tworzeniu stron internetowych, które znacznie ułatwia debugowanie. Na tej stronie znajdziesz podstawowe informacje o mapach źródłowych, w tym o tym, jak są generowane i jak ułatwiają debugowanie.

Potrzebujesz map źródłowych

Wczesne aplikacje internetowe były proste. Deweloperzy wdrożyli pliki HTML, CSS i JavaScript bezpośrednio do sieci.

Bardziej nowoczesne i złożone aplikacje internetowe mogą wymagać użycia różnych narzędzi w ramach procesu tworzenia. Na przykład:

Krótki przegląd różnych narzędzi.
Niektóre popularne narzędzia do tworzenia aplikacji internetowych.

Te narzędzia wymagają procesu kompilacji, aby przetłumaczyć kod na standardowy kod HTML, JavaScript i CSS, który rozumieją przeglądarki. Popularną praktyką jest też optymalizowanie wydajności przez kompresowanie i łączenie tych plików za pomocą narzędzia takiego jak Terser.

Za pomocą narzędzi do kompilacji możemy na przykład przetłumaczyć i skompresować ten plik TypeScript do pojedynczego wiersza kodu JavaScript. Możesz to sprawdzić samodzielnie w wersji demonstracyjnej na GitHubie.

/* 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);
});

Wersja skompresowana:

/* 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)}));

Jednak kompresowanie kodu może utrudnić debugowanie. Mapy źródeł mogą rozwiązać ten problem: dzięki zmapowaniu skompilowanego kodu na kod źródłowy mogą pomóc w szybkim znalezieniu źródła błędu.

Generowanie map źródłowych

Mapy źródeł to pliki, których nazwy kończą się na .map (np. example.min.js.mapstyles.css.map). Mogą być generowane przez większość narzędzi do kompilacji, w tym Vite, webpack, Rollup, Parcelesbuild.

Niektóre narzędzia domyślnie zawierają mapy źródłowe. Inne mogą wymagać dodatkowej konfiguracji, aby je wygenerować:

/* 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
 
}
})

Informacje o mapie źródeł

Aby ułatwić debugowanie, te pliki mapy źródeł zawierają istotne informacje o tym, jak skompilowany kod jest mapowany na kod źródłowy. Oto przykład mapy źródłowej:

{
 
"mappings": "AAAAA,SAASC,cAAc,WAAWC, ...",
 
"sources": ["src/script.ts"],
 
"sourcesContent": ["document.querySelector('button')..."],
 
"names": ["document","querySelector", ...],
 
"version": 3,
 
"file": "example.min.js.map"
}

Aby dowiedzieć się więcej o każdym z tych pól, przeczytaj specyfikację mapy źródeł lub artykuł Anatomia mapy źródeł.

Najważniejszym elementem mapy źródłowej jest pole mappings. Używa ona ciągu znaków z kodowaniem VLQ Base64, aby mapować linie i lokalizacje w skompilowanym pliku na odpowiadający im oryginalny plik. Możesz wyświetlić to mapowanie za pomocą wizualizacji mapy źródłowej, takiej jak source-map-visualization lub Source Map Visualization.

Wizualizacja mapy źródeł
Wizualizacja poprzedniego przykładu kodu wygenerowana przez visualizer.

Kolumna wygenerowana po lewej stronie zawiera skompresowany materiał, a kolumna oryginalny – jego oryginalne źródło.

Wizualizacja przypisuje kolor do każdego wiersza w kolumnie oryginalna, a następnie przypisuje odpowiedni kod do kolumny wygenerowana.

Sekcja mapowania zawiera odkodowane mapowania kodu. Na przykład wpis 65 -> 2:2 oznacza:

  • Wygenerowany kod: słowo const zaczyna się w pozycji 65 w skompresowanej treści.
  • Oryginalny kod: słowo const zaczyna się w wierszu 2 i kolumnie 2 w pierwotnej treści.
Wpis mapowania.
Wizualizacja mapowania z powiększeniem pozycji 65 -> 2:2.

Dzięki temu deweloperzy mogą szybko zidentyfikować relację między zminifikowanym kodem a pierwotnym kodem, co ułatwia debugowanie.

Mapy źródeł stosowane przez narzędzia programistyczne w przeglądarce pomagają szybko znajdować problemy w przeglądarce.

Narzędzia dla programistów stosujące mapę źródłową.
Przykład zastosowania przez narzędzia dewelopera przeglądarki map źródłowych i mapowania między plikami.

Rozszerzenia mapy źródłowej

Mapy źródeł obsługują niestandardowe pola rozszerzeń, które zaczynają się od prefiksu x_. Przykładem jest pole rozszerzenia x_google_ignoreList zaproponowane przez narzędzia programistyczne Chrome. Aby dowiedzieć się więcej o tym, jak te rozszerzenia pomagają Ci skupić się na kodzie, zapoznaj się z parametrem x_google_ignoreList.

Wady mapy źródłowej

Niestety mapowania źródeł nie zawsze są tak dokładne, jak byś chciał(-a). W pierwszym przykładzie zmienna greet została zoptymalizowana podczas procesu kompilacji, mimo że jej wartość jest bezpośrednio wbudowana w końcowym ciągu znaków.

Zmienna greet nie jest mapowana.
W mapowaniu brakuje zmiennej greet w pierwotnym kodzie.

W takim przypadku podczas debugowania kodu narzędzia dla programistów mogą nie być w stanie ustalić i wyświetlić rzeczywistej wartości. Ten rodzaj błędu może utrudniać monitorowanie i analizowanie kodu.

Zmienna greet jest niezdefiniowana.
Narzędzia dla deweloperów nie mogą znaleźć wartości dla greet.

Ten problem wymaga rozwiązania w ramach projektu map źródłowych. Jednym z potencjalnych rozwiązań jest uwzględnienie informacji o zakresie w mapach źródłowych w taki sam sposób, w jaki inne języki programowania podają informacje debugowania.

Wymaga to jednak współpracy całego ekosystemu w celu ulepszenia specyfikacji i implementacji map źródłowych. Aby śledzić postępy w ulepszaniu możliwości debugowania za pomocą map źródłowych, zapoznaj się z propozycją map źródłowych w wersji 4 na GitHubie.