source-map

中文文档

0.8.0发布于 2026/07/20BSD-3-ClauseTypeScriptCommonJS零依赖近 30 天下载 14.7亿

生成并使用源映射

文档目录10 节

与Node一起使用
在网上使用
目录表
例子
使用源映射
生成源映射
API
SourceMapConsumer
SourceMapGenerator
SourceNode

源图

这是一个生成和使用源映射格式的库这里描述。

与Node一起使用

$ npm install source-map

在网上使用

<script src="https://unpkg.com/[email protected]/dist/source-map.js"></script>
<script>
  sourceMap.SourceMapConsumer.initialize({
    "lib/mappings.wasm": "https://unpkg.com/[email protected]/lib/mappings.wasm",
  });
</script>

目录表

例子
- 使用源映射
- 生成源映射
  - 使用SourceNode（高级API）
  - 使用SourceMapGenerator（低级API）
API

例子

使用源映射

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，并调试与源映射

使用SourceNode（高级API）

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）

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

获取该模块的引用：

// 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。

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的索引。用于识别第三方源代码，开发人员在调试时可能想要避免。阅读更多

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

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

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 完成。

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数据。

consumer.destroy();

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

SourceMapConsumer.prototype.computeColumnSpans ()

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

// 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：原始标识符，如果此信息不可用，则为空。

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开始。

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开始。

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。

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

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

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

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

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。

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，禁用映射的验证它们是相加的。这可以提高性能，但应该与谨慎，作为最后的手段。即使这样，也应该避免使用这个标志运行测试，如果可能的话。

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

SourceMapGenerator.fromSourceMap (sourceMapConsumer)

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

sourceMapConsumer SourceMap。

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

SourceMapGenerator.prototype.addMapping(映射)

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

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

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

SourceMapGenerator.prototype。sourceContent setSourceContent(源文件)

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

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

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 ()

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

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:可选的。原始标识符。

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 应该是相对的。

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，或者一个数组，其中每个成员都是这些元素中的一个。

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

SourceNode.prototype.prepend(块)

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

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

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

SourceNode.prototype。sourceContent setSourceContent(源文件)

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

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

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

SourceNode.prototype.walk (fn)

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

fn：遍历函数。

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：遍历函数。

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：分隔符。

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：用来代替图案的东西。

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

SourceNode.prototype.toString ()

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

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。

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 共发布 71 个版本，首次发布于 2011/08/31；过去 12 个月发布了 1 个版本。

版本	发布日期	距今
`0.8.0`latest	2026/07/20	3 个月前
`0.7.6`	2025/07/24	1.3 年前
`0.7.5`next	2025/07/24	1.3 年前
`0.7.4`	2022/06/05	4 年前
`0.8.0-beta.0`	2018/11/16	7 年前
`0.7.3`	2018/05/17	8 年前

关于 source-map 的常见问题

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 和提交记录判断。

npm install source-map

pnpmpnpm add source-map
yarnyarn add source-map
bunbun add source-map

在你的项目目录中运行此命令。

近 30 天下载

1,472,688,009

约 14.7亿次日均 49,089,600 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，今天更新

最新版本0.8.0发布于 3 个月前

开源许可BSD-3-Clause宽松许可

包体积186 kB19 个文件 · 解压后

运行依赖0 个零依赖

模块格式CommonJS

TypeScript自带类型

Node.js>= 12

发布版本71 个近 12 个月 1 个

首次发布2011/08/3115 年前

元数据更新2026/10/22

每一个软件包背后，
都有分享与创造的人。