# source-map 中文文档

规范地址：https://npmcn.com/package/source-map/

版本：0\.8\.0
npm 元数据更新时间：2026-10-22T10:56:45.044Z
中文译文更新时间：2026-11-04T10:36:16.884Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/source-map
原文对照：https://npmcn.com/package/source-map/?lang=original
项目主页：https://github.com/mozilla/source-map
源码仓库：https://github.com/mozilla/source-map

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：186 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 12
- 运行依赖：0 个
- 首次发布：2011-08-30T19:45:39.150Z
- 最新版本发布：2026-07-20T05:45:25.965Z
- 近 30 天下载量：1472688009（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 1 个）

## 中文简介

生成并使用源映射

## 安装

```sh
npm install source-map
```

也可以使用：`pnpm add source-map`、`yarn add source-map`、`bun add source-map`

## README

# 源图

[![NPM](https://nodei.co/npm/source-map.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map)

这是一个生成和使用源映射格式的库 [这里描述](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit)。

## 与Node一起使用

```
$ npm install source-map
```

## 在网上使用

```html
<script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script>
<script>
  sourceMap.SourceMapConsumer.initialize({
    "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm",
  });
</script>
```

* * *

## 目录表

-   [例子](https://npmcn.com/package/source-map/#readme-examples)
    -   [使用源映射](https://npmcn.com/package/source-map/#readme-consuming-a-source-map)
    -   [生成源映射](https://npmcn.com/package/source-map/#readme-generating-a-source-map)
        -   [使用SourceNode（高级API）](https://npmcn.com/package/source-map/#readme-with-sourcenode-high-level-api)
        -   [使用SourceMapGenerator（低级API）](https://npmcn.com/package/source-map/#readme-with-sourcemapgenerator-low-level-api)
-   [API](https://npmcn.com/package/source-map/#readme-api)
    -   [SourceMapConsumer](https://npmcn.com/package/source-map/#readme-sourcemapconsumer)
        -   [SourceMapConsumer.initialize(选项)](https://npmcn.com/package/source-map/#readme-sourcemapconsumerinitializeoptions)
        -   [新SourceMapConsumer (rawSourceMap)](https://npmcn.com/package/source-map/#readme-new-sourcemapconsumerrawsourcemap)
        -   [SourceMapConsumer.with](https://npmcn.com/package/source-map/#readme-sourcemapconsumerwith)
        -   [SourceMapConsumer.prototype.destroy ()](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypedestroy)
        -   [SourceMapConsumer.prototype.computeColumnSpans ()](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypecomputecolumnspans)
        -   [SourceMapConsumer.prototype.originalPositionFor (generatedPosition)](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
        -   [SourceMapConsumer.prototype.generatedPositionFor (originalPosition)](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypegeneratedpositionfororiginalposition)
        -   [SourceMapConsumer.prototype.allGeneratedPositionsFor (originalPosition)](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
        -   [SourceMapConsumer.prototype.hasContentsOfAllSources ()](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypehascontentsofallsources)
        -   [SourceMapConsumer.prototype。sourceContentFor(源\[,returnNullOnMissing\])](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
        -   [SourceMapConsumer.prototype。eachMapping（callback, context, order）](https://npmcn.com/package/source-map/#readme-sourcemapconsumerprototypeeachmappingcallback-context-order)
    -   [SourceMapGenerator](https://npmcn.com/package/source-map/#readme-sourcemapgenerator)
        -   [新SourceMapGenerator (\[startOfSourceMap\])](https://npmcn.com/package/source-map/#readme-new-sourcemapgeneratorstartofsourcemap)
        -   [SourceMapGenerator.fromSourceMap (sourceMapConsumer)](https://npmcn.com/package/source-map/#readme-sourcemapgeneratorfromsourcemapsourcemapconsumer)
        -   [SourceMapGenerator.prototype.addMapping(映射)](https://npmcn.com/package/source-map/#readme-sourcemapgeneratorprototypeaddmappingmapping)
        -   [SourceMapGenerator.prototype。sourceContent setSourceContent(源文件)](https://npmcn.com/package/source-map/#readme-sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
        -   [SourceMapGenerator.prototype。applySourceMap（sourceMapConsumer\[, sourceFile\[, sourceMapPath\]\]）](https://npmcn.com/package/source-map/#readme-sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
        -   [SourceMapGenerator.prototype.toString ()](https://npmcn.com/package/source-map/#readme-sourcemapgeneratorprototypetostring)
    -   [SourceNode](https://npmcn.com/package/source-map/#readme-sourcenode)
        -   [new SourceNode（\[line, column, source\[, chunk\[, name\]\]）](https://npmcn.com/package/source-map/#readme-new-sourcenodeline-column-source-chunk-name)
        -   [SourceNode.fromStringWithSourceMap（code, sourceMapConsumer\[, relativePath\]）](https://npmcn.com/package/source-map/#readme-sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
        -   [SourceNode.prototype.add(块)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypeaddchunk)
        -   [SourceNode.prototype.prepend(块)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypeprependchunk)
        -   [SourceNode.prototype。sourceContent setSourceContent(源文件)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
        -   [SourceNode.prototype.walk (fn)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypewalkfn)
        -   [SourceNode.prototype.walkSourceContents (fn)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypewalksourcecontentsfn)
        -   [SourceNode.prototype.join(9月)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypejoinsep)
        -   [SourceNode.prototype。replaceRight(模式、更换)](https://npmcn.com/package/source-map/#readme-sourcenodeprototypereplacerightpattern-replacement)
        -   [SourceNode.prototype.toString ()](https://npmcn.com/package/source-map/#readme-sourcenodeprototypetostring)
        -   [SourceNode.prototype.toStringWithSourceMap (\[startOfSourceMap\])](https://npmcn.com/package/source-map/#readme-sourcenodeprototypetostringwithsourcemapstartofsourcemap)

## 例子

### 使用源映射

```js
const rawSourceMap = {
  version: 3,
  file: "min.js",
  names: ["bar", "baz", "n"],
  sources: ["one.js", "two.js"],
  sourceRoot: "http://example.com/www/js/",
  mappings:
    "CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA",
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {
  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(
    consumer.originalPositionFor({
      line: 2,
      column: 28,
    })
  );
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(
    consumer.generatedPositionFor({
      source: "http://example.com/www/js/two.js",
      line: 2,
      column: 10,
    })
  );
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});
```

### 生成源映射

深入指南： [**编译成JavaScript，并调试与源映射**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)

#### 使用SourceNode（高级API）

```js
function compile(ast) {
  switch (ast.type) {
    case "BinaryExpression":
      return new SourceNode(
        ast.location.line,
        ast.location.column,
        ast.location.source,
        [compile(ast.left), " + ", compile(ast.right)]
      );
    case "Literal":
      return new SourceNode(
        ast.location.line,
        ast.location.column,
        ast.location.source,
        String(ast.value)
      );
    // ...
    default:
      throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(
  compile(ast).toStringWithSourceMap({
    file: "add.js",
  })
);
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }
```

#### 使用SourceMapGenerator（低级API）

```js
var map = new SourceMapGenerator({
  file: "source-mapped.js",
});

map.addMapping({
  generated: {
    line: 10,
    column: 35,
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2,
  },
  name: "christopher",
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
```

## API

获取该模块的引用：

```js
// Node.js
var sourceMap = require("source-map");

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
```

### SourceMapConsumer

一个 `SourceMapConsumer` Instance表示可以查询的解析过的源映射 通过给它一个文件位置来获取有关原始文件位置的信息 在生成的源文件中。

#### SourceMapConsumer.initialize(选项)

当使用 `SourceMapConsumer` 在node.js之外，例如在Web上，它 需要知道从哪个URL加载 `lib/mappings.wasm`。你必须通知它 调用 `initialize` 在构造任何 `SourceMapConsumer`年代。

options对象有以下属性：

-   `"lib/mappings.wasm"`:一个 `String` 的URL `lib/mappings.wasm` 文件，或者 `ArrayBuffer` 的内容 `lib/mappings.wasm`。

```js
sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm",
});
```

#### 新SourceMapConsumer (rawSourceMap)

唯一的参数是原始源映射(可以是字符串，也可以是 `JSON.parse`'d，或一个对象)。根据规范，源映射具有 以下属性:

-   `version`：此映射遵循源映射规范的哪个版本。
    
-   `sources`：指向原始源文件的url数组。
    
-   `names`：可供个人引用的标识符数组 映射。
    
-   `sourceRoot`:可选的。URL根，所有源都是相对的。
    
-   `sourcesContent`:可选的。原始源文件的内容数组。
    
-   `mappings`：包含实际映射的base64 vlq字符串。
    
-   `file`:可选的。与此源映射相关联的生成的文件名。
    
-   `x_google_ignoreList`:可选的。一个额外的扩展字段，它是一个数组 引用源数组中url的索引。用于识别第三方 源代码，开发人员在调试时可能想要避免。 [阅读更多](https://developer.chrome.com/articles/x-google-ignore-list/)
    

返回构造的源映射消费者的承诺。

当 `SourceMapConsumer` 将不再使用，你必须调用其 `destroy` 方法。

```js
const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
doStuffWith(consumer);
consumer.destroy();
```

或者，您可以使用 `SourceMapConsumer.with` 为了避免记忆 打电话给 `destroy`。

#### SourceMapConsumer.with

构建一个新的 `SourceMapConsumer` 从 `rawSourceMap` 和 `sourceMapUrl` (见 `SourceMapConsumer` 构造函数。然后，调用 `async function f(SourceMapConsumer) -> T` 对于新构建的消费者，等待 为 `f` 要完成，请调用 `destroy` 上了消费者，又回来了 `f`的回报 价值。

你不能使用消费后 `f` 完成!

通过使用 `with`，您不必记得手动呼叫 `destroy` 在 消费者，因为它将被自动调用一次 `f` 完成。

```js
const xSquared = await SourceMapConsumer.with(
  myRawSourceMap,
  null,
  async function (consumer) {
    // Use `consumer` inside here and don't worry about remembering
    // to call `destroy`.

    const x = await whatever(consumer);
    return x * x;
  }
);

// You may not use that `consumer` anymore out here; it has
// been destroyed. But you can use `xSquared`.
console.log(xSquared);
```

#### SourceMapConsumer.prototype.destroy ()

释放此源映射使用者手动管理的相关wasm数据。

```js
consumer.destroy();
```

或者，您可以使用 `SourceMapConsumer.with` 为了避免记忆 打电话给 `destroy`。

#### SourceMapConsumer.prototype.computeColumnSpans ()

为每个生成的映射计算最后一列。最后一列是 包容性。

```js
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" });
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" });
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]
```

#### SourceMapConsumer.prototype.originalPositionFor (generatedPosition)

返回生成的对象的原始源、行和列信息 提供源的行和列位置。唯一的实参是一个带的对象 以下属性：

-   `line`：生成源文件中的行号。中的行号 这个库是基于1的（注意底层的源映射） 规范使用基于0的行号——这个库处理 翻译)。
    
-   `column`：生成源中的列号。列数字 在这个库中是基于0的。
    
-   `bias`:要么 `SourceMapConsumer.GREATEST_LOWER_BOUND` 或 `SourceMapConsumer.LEAST_UPPER_BOUND`。指定是否返回最近的 小于或大于我们要查找的元素， 分别，如果找不到确切的元素。默认为 `SourceMapConsumer.GREATEST_LOWER_BOUND`。
    

返回一个具有以下属性的对象：

-   `source`：原始的源文件，如果该信息不是，则为空 可用。
    
-   `line`：原始源代码中的行号，如果该信息为，则为空 不可用。行号从1开始。
    
-   `column`：原始源中的列号，如果是，则为空 没有相关信息。列号从0开始。
    
-   `name`：原始标识符，如果此信息不可用，则为空。
    

```js
consumer.originalPositionFor({ line: 2, column: 10 });
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({
  line: 99999999999999999,
  column: 999999999999999,
});
// { source: null,
//   line: null,
//   column: null,
//   name: null }
```

#### SourceMapConsumer.prototype.generatedPositionFor (originalPosition)

返回为原始源生成的行和列信息， 提供了行和列位置。唯一的实参是一个带的对象 以下属性：

-   `source`：原始源文件的文件名。
    
-   `line`：原始源代码中的行号。行号为 基于。
    
-   `column`：原源中的列号。列 数字是从0开始的。
    

返回一个具有以下属性的对象：

-   `line`：生成源文件中的行号，或者为空。线 数字是从1开始的。
    
-   `column`：生成源中的列号，或为空。这个 列号从0开始。
    

```js
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 });
// { line: 1,
//   column: 56 }
```

#### SourceMapConsumer.prototype.allGeneratedPositionsFor (originalPosition)

返回为原始源、行、 列提供。如果没有提供列，则返回所有映射 对应于我们正在搜索的行或下一个最近的行 它有任何映射。对象对应的所有映射 给定的行和我们正在搜索的列或下一个最近的列 它有任何抵消。

唯一的参数是一个具有以下属性的对象：

-   `source`：原始源文件的文件名。
    
-   `line`：原始源代码中的行号。行号为 基于。
    
-   `column`:可选的。原始源中的列号。这个 列号从0开始。
    

并返回一个对象数组，每个对象都具有以下属性：

-   `line`：生成源文件中的行号，或者为空。线 数字是从1开始的。
    
-   `column`：生成源中的列号，或为空。这个 列号从0开始。
    

```js
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" });
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]
```

#### SourceMapConsumer.prototype.hasContentsOfAllSources ()

中列出的每个源都嵌入了源内容，则返回true 源映射，否则为false。

换句话说，如果这个方法返回 `true`,然后 `consumer.sourceContentFor(s)` 每个来源都能成功吗 `s` 在 `consumer.sources`。

```js
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...
```

#### SourceMapConsumer.prototype。sourceContentFor(源\[,returnNullOnMissing\])

返回所提供源的原始源内容。唯一的 参数是原始源文件的URL。

如果没有找到给定源的源内容，则会出现错误 抛出。可选地,通过 `true` 作为第二个参数 `null` 返回 代替。

```js
consumer.sources;
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj");
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null
```

#### SourceMapConsumer.prototype。eachMapping（callback, context, order）

遍历原始源/行/列与a之间的每个映射 在此源映射中生成的行/列。

-   `callback`：每次映射调用的函数。映射具有 形式 `{ source, generatedLine, generatedColumn, originalLine, originalColumn, name }`。
    
-   `context`:可选的。如果指定，该对象将是的值 `this` 每次 `callback` 被称为。
    
-   `order`:要么 `SourceMapConsumer.GENERATED_ORDER` 或 `SourceMapConsumer.ORIGINAL_ORDER`。指定是否要遍历 按生成文件的行/列顺序或 原文的来源/行/列顺序分别。默认为 `SourceMapConsumer.GENERATED_ORDER`。
    

```js
consumer.eachMapping(function (m) {
  console.log(m);
});
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...
```

### SourceMapGenerator

SourceMapGenerator的一个实例表示正在被生成的源映射 逐步建立的。

#### 新SourceMapGenerator (\[startOfSourceMap\])

你可以传递一个具有以下属性的对象：

-   `file`：此源映射所生成的源的文件名 联系在一起。
    
-   `sourceRoot`：此源映射中所有相对url的根。
    
-   `skipValidation`:可选的。当 `true`，禁用映射的验证 它们是相加的。这可以提高性能，但应该与 谨慎，作为最后的手段。即使这样，也应该避免使用这个标志 运行测试，如果可能的话。
    

```js
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/",
});
```

#### SourceMapGenerator.fromSourceMap (sourceMapConsumer)

创建一个新的 `SourceMapGenerator` 从现有的 `SourceMapConsumer` 实例。

-   `sourceMapConsumer` SourceMap。

```js
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);
```

#### SourceMapGenerator.prototype.addMapping(映射)

将原始源行和列的单个映射添加到生成的 正在创建的源映射的源行和列。映射对象 应具有以下属性：

-   `generated`：具有生成的行和列位置的对象。
    
-   `original`：具有原始线和列位置的对象。
    
-   `source`：原始源文件（相对于sourceRoot）。
    
-   `name`：此映射的可选原始令牌名称。
    

```js
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 },
});
```

#### SourceMapGenerator.prototype。sourceContent setSourceContent(源文件)

为原始源文件设置源内容。

-   `sourceFile` 原始源文件的URL。
    
-   `sourceContent` 源文件的内容。
    

```js
generator.setSourceContent(
  "module-one.scm",
  fs.readFileSync("path/to/module-one.scm")
);
```

#### SourceMapGenerator.prototype。applySourceMap（sourceMapConsumer\[, sourceFile\[, sourceMapPath\]\]）

将源文件的SourceMap应用于SourceMap。 方法重写到所提供源文件的每个映射 SourceMap提供。注意：结果映射的分辨率 是这个地图和提供的地图的最小值。

-   `sourceMapConsumer`要应用的SourceMap。
    
-   `sourceFile`:可选的。源文件的文件名。 如果省略，则将使用sourceMapConsumer.file（如果存在）。 否则将抛出错误。
    
-   `sourceMapPath`:可选的。SourceMap的路径的dirname 待应用的如果是相对的，它是相对于SourceMap的。
    
    当两个SourceMaps不相同时需要此参数 目录，并且要应用的SourceMap包含相对源 路径。如果是这样，则需要重写这些相对源路径 相对于SourceMap。
    
    如果省略，则假定两个SourceMaps都在同一目录中， 因此不需要任何重写。(提供 `'.'` 具有相同的效果。)
    

#### SourceMapGenerator.prototype.toString ()

将生成的源映射呈现为字符串。

```js
generator.toString();
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
```

### SourceNode

sourcenode提供了一种超越插值和/或连接的抽象方式 生成的JavaScript源代码片段，同时维护行和 在这些片段和原始源之间关联的列信息 代码。这是编译器可能使用的最终中间表示形式 在输出生成的JS和源映射之前使用。

#### new SourceNode（\[line, column, source\[, chunk\[, name\]\]）

-   `line`：与此源节点关联的原始行号，如果为空，则为空 它与原始的线没有关联。行号从1开始。
    
-   `column`：与此源节点关联的原始列号，或者为空 如果它不与原始列关联。列号 是基于0。
    
-   `source`：原始源文件的文件名；如果没有提供文件名，则为空。
    
-   `chunk`:可选的。立即传递给 `SourceNode.prototype.add`,看 在下面。
    
-   `name`:可选的。原始标识符。
    

```js
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);
```

#### SourceNode.fromStringWithSourceMap（code, sourceMapConsumer\[, relativePath\]）

从生成的代码和SourceMapConsumer中创建一个SourceNode。

-   `code`：生成的代码。
    
-   `sourceMapConsumer` 生成代码的SourceMap。
    
-   `relativePath` 相对源所在的可选路径 `sourceMapConsumer` 应该是相对的。
    

```js
const consumer = await new SourceMapConsumer(
  fs.readFileSync("path/to/my-file.js.map", "utf8")
);
const node = SourceNode.fromStringWithSourceMap(
  fs.readFileSync("path/to/my-file.js"),
  consumer
);
```

#### SourceNode.prototype.add(块)

将生成的JS块添加到该源节点。

-   `chunk`生成的JS代码的字符串片段，另一个实例 `SourceNode`，或者一个数组，其中每个成员都是这些元素中的一个。

```js
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
```

#### SourceNode.prototype.prepend(块)

将生成的JS块添加到该源节点。

-   `chunk`生成的JS代码的字符串片段，另一个实例 `SourceNode`，或者一个数组，其中每个成员都是这些元素中的一个。

```js
node.prepend("/** Build Id: f783haef86324gf **/\n\n");
```

#### SourceNode.prototype。sourceContent setSourceContent(源文件)

设置源文件的源内容。这将被添加到 `SourceMap` 在 `sourcesContent` 字段。

-   `sourceFile`：源文件的文件名。
    
-   `sourceContent`：源文件的内容。
    

```js
node.setSourceContent(
  "module-one.scm",
  fs.readFileSync("path/to/module-one.scm")
);
```

#### SourceNode.prototype.walk (fn)

遍历该节点及其子节点中的JS片段树。行走 函数在JS的每个代码片段中调用一次，并传递该代码片段和 其原始关联源的行/列位置。

-   `fn`：遍历函数。

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  ["tres", new SourceNode(5, 6, "c.js", "quatro")],
]);

node.walk(function (code, loc) {
  console.log("WALK:", code, loc);
});
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
```

#### SourceNode.prototype.walkSourceContents (fn)

浏览sourcenode树。每个函数都调用遍历函数 源文件内容，并传递文件名和源内容。

-   `fn`：遍历函数。

```js
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) {
  console.log("WALK:", source, ":", contents);
});
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c
```

#### SourceNode.prototype.join(9月)

就像 `Array.prototype.join` 除了sourcenode。插入分隔符 在此源节点的每个子节点之间。

-   `sep`：分隔符。

```js
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [lhs, operand, rhs]);
var joinedNode = node.join(" ");
```

#### SourceNode.prototype。replaceRight(模式、更换)

呼叫 `String.prototype.replace` 在最右边的源代码片段中。有用的 用于从源节点等的末端修剪空白。

-   `pattern`：要替换的图案。
    
-   `replacement`：用来代替图案的东西。
    

```js
// Trim trailing white space.
node.replaceRight(/\s*$/, "");
```

#### SourceNode.prototype.toString ()

返回此源节点的字符串表示形式。走过树，然后 将所有不同的片段连接到一个字符串中。

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  ["tres", new SourceNode(5, 6, "c.js", "quatro")],
]);

node.toString();
// 'unodostresquatro'
```

#### SourceNode.prototype.toStringWithSourceMap (\[startOfSourceMap\])

返回此源节点树的字符串表示形式，加上a SourceMapGenerator，它包含生成的和 最初的来源。

参数与to的参数相同 `new SourceMapGenerator`。

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  ["tres", new SourceNode(5, 6, "c.js", "quatro")],
]);

node.toStringWithSourceMap({ file: "my-output-file.js" });
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
```

## 常见问题

### source-map 是什么？

生成并使用源映射

### 如何安装 source-map？

在项目目录运行 npm install source-map，或使用 pnpm add / yarn add / bun add。

### source-map 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### source-map 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### source-map 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### source-map 可以商用吗？

source-map 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### source-map 的下载量有多少？

根据 npm 官方下载统计，source-map 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,472,688,009 次，日均约 49,089,600 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### source-map 还在维护吗？

最新版本 0\.8\.0 发布于 2026/07/20（3 个月前）；至今共发布 71 个版本，其中过去 12 个月发布了 1 个；首次发布于 2011/08/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。