Co to są mapy źródeł?

Jecelyn Yeen

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.map i styles.css.map). Mogą być generowane przez większość narzędzi do kompilacji, w tym Vite, webpack, Rollup, Parcel i esbuild.

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.