原始碼地圖

Parcel 使用 @parcel/source-map 套件處理原始碼對應，以確保在各種外掛和 Parcel 核心之間處理原始碼對應時，效能與可靠性。這個函式庫完全使用 Rust 編寫，效能比先前的 JavaScript 實作提升了 20 倍。效能提升主要歸功於資料結構和快取原始碼對應方式的最佳化。

如何使用函式庫

如要使用 @parcel/source-map，請建立匯出的 SourceMap 類別實例，然後可以在實例上呼叫各種函式來新增和編輯原始碼對應。應將 projectRoot 目錄路徑傳遞為引數。原始碼對應中的所有路徑都轉換為相對於此目錄的路徑。

以下是涵蓋所有將對應新增至 SourceMap 實例方式的範例

import SourceMap from '@parcel/source-map';

let sourcemap = new SourceMap(projectRoot);

// Each function that adds mappings has optional offset arguments.
// These can be used to offset the generated mappings by a certain amount.
let lineOffset = 0;
let columnOffset = 0;

// Add indexed mappings
// These are mappings that can sometimes be extracted from a library even before they get converted into VLQ Mappings
sourcemap.addIndexedMappings(
  [
    {
      generated: {
        // line index starts at 1
        line: 1,
        // column index starts at 0
        column: 4,
      },
      original: {
        // line index starts at 1
        line: 1,
        // column index starts at 0
        column: 4,
      },
      source: "index.js",
      // Name is optional
      name: "A",
    },
  ],
  lineOffset,
  columnOffset
);

// Add vlq mappings. This is what would be outputted into a vlq encoded source map
sourcemap.addVLQMap(
  {
    file: "min.js",
    names: ["bar", "baz", "n"],
    sources: ["one.js", "two.js"],
    sourceRoot: "/the/root",
    mappings:
      "CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA",
  },
  lineOffset,
  columnOffset
);

// Source maps can be serialized to buffers, which is what we use for caching in Parcel.
// You can instantiate a SourceMap with these buffer values by passing it to the constructor
let map = new SourceMap(projectRoot, mapBuffer);

// You can also add a buffer to an existing source map using the addBuffer method.
sourcemap.addBuffer(originalMapBuffer, lineOffset);

// One SourceMap object may be added to another using the addSourceMap method.
sourcemap.addSourceMap(map, lineOffset);

轉換/處理

如果外掛執行任何程式碼處理，應確保它建立正確對應至原始程式碼，以保證我們最後仍能建立精確的原始碼對應。您預期在 轉換器 外掛的轉換結束時傳回 SourceMap 實例。

我們也提供前一個轉換的來源地圖，以確保您對應到原始的原始碼，而不仅仅是前一個轉換的輸出。如果編譯器沒有辦法傳入輸入來源地圖，您可以使用 SourceMap 的 extends 方法將原始對應關係對應到已編譯的對應關係。

傳遞給轉換器外掛程式的 parse、transform 和 generate 函式的 asset 值包含一個稱為 getMap() 和 getMapBuffer() 的函式。這些函式可用於取得 SourceMap 實例 (getMap()) 和快取的 SourceMap Buffer (getMapBuffer())。

只要確保 generate 中傳回的來源地圖正確對應到原始來源檔案，您就可以在轉換器的這些步驟中自由地操作來源地圖。

以下是如何在轉換器外掛程式中操作來源地圖的範例

import {Transformer} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Transformer({
  // ...

  async generate({asset, ast, resolve, options}) {
    let compilationResult = someCompiler(await asset.getAST());

    let map = null;
    if (compilationResult.map) {
      // If the compilationResult returned a map we convert 
      // it to a Parcel SourceMap instance.
      map = new SourceMap(options.projectRoot);

      // The compiler returned a full, encoded sourcemap with vlq mappings.
      // Some compilers might have the possibility of returning 
      // indexedMappings which might improve performance (like Babel does).
      // In general, every  compiler is able to return rawMappings, so
      // it's always a safe bet to use this.
      map.addVLQMap(compilationResult.map);

      // We get the original source map from the asset to extend our mappings 
      // on top of it. This ensures we are mapping to the original source
      // instead of the previous transformation.
      let originalMap = await asset.getMap();
      if (originalMap) {
        // The `extends` function uses the provided map to remap the original 
        // source positions of the map it is called on. In this case, the 
        // original source positions of `map` get remapped to the positions 
        // in `originalMap`.
        map.extends(originalMap);
      }
    }

    return {
      code: compilationResult.code,
      map,
    };
  },
});

如果您的編譯器支援傳入現有來源地圖的選項，這可能會產生比使用前一個範例中的方法更精確的來源地圖。

這將如何運作的範例

import {Transformer} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Transformer({
  // ...

  async generate({asset, ast, resolve, options}) {
    // Get the original map from the asset.
    let originalMap = await asset.getMap();
    let compilationResult = someCompiler(await asset.getAST(), {
      // Pass the VLQ encoded version of the originalMap to the compiler.
      originalMap: originalMap.toVLQ(),
    });

    // In this case the compiler is responsible for mapping to the original 
    // positions provided in the originalMap, so we can just convert it to 
    // a Parcel SourceMap and return it.
    let map = new SourceMap(options.projectRoot);
    if (compilationResult.map) {
      map.addVLQMap(compilationResult.map);
    }

    return {
      code: compilationResult.code,
      map,
    };
  },
});

在封裝器中串接來源地圖

如果您正在撰寫自訂封裝器，您有責任在封裝時串接所有資源的來源地圖。這是透過建立新的 SourceMap 實例，並使用 addSourceMap(map, lineOffset) 函式新增新的對應關係來完成的。lineOffset 應等於資源輸出開始的行索引。

以下是如何執行的範例

import {Packager} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Packager({
  async package({bundle, options}) {
    // Read content and source maps for each asset in the bundle.
    let promises = [];
    bundle.traverseAssets(asset => {
      promises.push(Promise.all([
        asset.getCode(),
        asset.getMap()
      ]);
    });

    let results = await Promise.all(promises);

    // Instantiate a string to hold the bundle contents, and
    // a SourceMap to hold the combined bundle source map.
    let contents = '';
    let map = new SourceMap(options.projectRoot);
    let lineOffset = 0;

    // Add the contents of each asset.
    for (let [code, map] of assets) {
      contents += code + '\n';

      // Add the source map if the asset has one, and offset
      // it by the number of lines in the bundle so far.
      if (map) {
        map.addSourceMap(map, lineOffset);
      }

      // Add the number of lines in this asset.
      lineOffset += countLines(code) + 1;
    }

    // Return the contents and map.
    return {contents, map};
  },
});

串接 AST

如果您串接 AST 而不是來源內容，您已經將來源對應關係嵌入到 AST 中，您可以使用它來產生最終的來源地圖。但是，您必須確保在編輯 AST 節點時這些對應關係保持完整。如果您進行大量的修改，有時這可能會非常具有挑戰性。

這如何運作的範例

import {Packager} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Packager({
  async package({bundle, options}) {
    // Do the AST concatenation and return the compiled result
    let compilationResult = concatAndCompile(bundle);

    // Create the final packaged sourcemap
    let map = new SourceMap(options.projectRoot);
    if (compilationResult.map) {
      map.addVLQMap(compilationResult.map);
    }

    // Return the compiled code and map
    return {
      code: compilationResult.code,
      map,
    };
  },
});

在最佳化器中進行後處理原始碼對應

在最佳化器中使用原始碼對應的方式與在轉換器中使用的方式相同。您取得一個檔案作為輸入，並預期傳回同一個檔案作為輸出，但已最佳化。

與最佳化器唯一的不同點在於，對應並非提供為資產的一部分，而是提供為一個獨立的參數/選項，如下列程式碼片段所示。對應始終是 SourceMap 類別的執行個體。

import {Optimizer} from '@parcel/plugin';

export default new Optimizer({
  // The contents and map are passed separately
  async optimize({bundle, contents, map}) {
    return {contents, map};
  }
});

診斷問題

如果您遇到不正確的對應，並想要除錯這些問題，我們已建置可協助您診斷這些問題的工具。透過執行 @parcel/reporter-sourcemap-visualiser 報告器，Parcel 會建立一個 sourcemap-info.json 檔案，其中包含視覺化所有對應和原始碼內容所需的所有資訊。

若要啟用它，請使用 --reporter 選項，或將它新增至您的 .parcelrc。

parcel build src/index.js --reporter @parcel/reporter-sourcemap-visualiser

報告器建立 sourcemap-info.json 檔案後，您可以將它上傳至 原始碼對應視覺化器。

API

interface SourceMap {

  constructor(projectRoot: string, buffer?: Buffer): void,

  libraryVersion(): string,

  static generateEmptyMap(v: GenerateEmptyMapOptions): SourceMap,

  addEmptyMap(sourceName: string, sourceContent: string, lineOffset: number): SourceMap,

  addVLQMap(map: VLQMap, lineOffset: number, columnOffset: number): SourceMap,

  addSourceMap(sourcemap: SourceMap, lineOffset: number): SourceMap,

  addBuffer(buffer: Buffer, lineOffset: number): SourceMap,

  addIndexedMapping(mapping: IndexedMapping<string>, lineOffset?: number, columnOffset?: number): void,

  _indexedMappingsToInt32Array(mappings: Array<IndexedMapping<string>>, lineOffset?: number, columnOffset?: number): Int32Array,

  addIndexedMappings(mappings: Array<IndexedMapping<string>>, lineOffset?: number, columnOffset?: number): SourceMap,

  addName(name: string): number,

  addNames(names: Array<string>): Array<number>,

  addSource(source: string): number,

  addSources(sources: Array<string>): Array<number>,

  getSourceIndex(source: string): number,

  getSource(index: number): string,

  getSources(): Array<string>,

  setSourceContent(sourceName: string, sourceContent: string): void,

  getSourceContent(sourceName: string): string | null,

  getSourcesContent(): Array<string | null>,

  getSourcesContentMap(): {
    [key: string]: string | null
  },

  getNameIndex(name: string): number,

  getName(index: number): string,

  getNames(): Array<string>,

  getMappings(): Array<IndexedMapping<number>>,

  indexedMappingToStringMapping(mapping: ?IndexedMapping<number>): ?IndexedMapping<string>,

  extends(buffer: Buffer | SourceMap): SourceMap,

  getMap(): ParsedMap,

  findClosestMapping(line: number, column: number): ?IndexedMapping<string>,

  offsetLines(line: number, lineOffset: number): ?IndexedMapping<string>,

  offsetColumns(line: number, column: number, columnOffset: number): ?IndexedMapping<string>,

  toBuffer(): Buffer,

  toVLQ(): VLQMap,

  delete(): void,

  stringify(options: SourceMapStringifyOptions): Promise<string | VLQMap>,

}

type MappingPosition = {|

  line: number,

  column: number,

|}

type IndexedMapping<T> = {

  generated: MappingPosition,

  original?: MappingPosition,

  source?: T,

  name?: T,

}

type ParsedMap = {|

  sources: Array<string>,

  names: Array<string>,

  mappings: Array<IndexedMapping<number>>,

  sourcesContent: Array<string | null>,

|}

type VLQMap = {

  +sources: $ReadOnlyArray<string>,

  +sourcesContent?: $ReadOnlyArray<string | null>,

  +names: $ReadOnlyArray<string>,

  +mappings: string,

  +version?: number,

  +file?: string,

  +sourceRoot?: string,

}

type SourceMapStringifyOptions = {

  file?: string,

  sourceRoot?: string,

  inlineSources?: boolean,

  fs?: {
    readFile(path: string, encoding: string): Promise<string>,
    ...
  },

  format?: 'inline' | 'string' | 'object',

}

type GenerateEmptyMapOptions = {

  projectRoot: string,

  sourceName: string,

  sourceContent: string,

  lineOffset?: number,

}