source-map-js

中文文档

1.2.2发布于 2026/09/30BSD-3-ClauseTypeScriptCommonJS零依赖近 30 天下载 8.6亿

生成并使用源映射

文档目录9 节

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

源地图JS

原始差异源图：

这是原创的一个分支 [email protected]，但具有性能优化。

这段旅程从 [email protected]．它的一部分被重写为Rust， WASM和API变成了异步。

它仍然是许多库的主要障碍，比如PostCSS或Sass，因为它们需要将整个API迁移到异步方式。这就是为什么0.6.1的下载量是0.7.3的两倍，而且速度是0.7.3的几倍。

Downloads count

更重要的是，WASM版本在JS代码中也有一些优化。这就是为什么社区要求为0.6版本创建分支并移植这些优化，但遗憾的是，答案是“不”。过了一会儿我才发现这个问题由本·罗斯曼（@benthemonkey）没有任何回应。

罗曼·德沃诺夫（@lahmatiy）写了一个几个帖子（俄语，只有，对不起）关于他自己的电报频道的源地图库。他提到了那篇文章也许你不需要Rust和WASM来加速你的JS 写的 Vyacheslav Egorov （@mraleph）．本文包含与WASM实现相比性能几乎相同的优化和hack。

我决定派生原始源映射，并从本文和原始源映射的其他几个PR中移植这些优化。

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

与Node一起使用

$ npm install source-map-js

目录表

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

例子

使用源映射

var 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'
};

var smc = new SourceMapConsumer(rawSourceMap);

console.log(smc.sources);
// [ 'http://example.com/www/js/one.js',
//   'http://example.com/www/js/two.js' ]

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

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

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

生成源映射

深入指南： 编译成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实例表示可以查询的解析源映射通过给它一个文件位置来获取有关原始文件位置的信息在生成的源文件中。

新SourceMapConsumer (rawSourceMap)

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

version：此映射遵循源映射规范的哪个版本。
sources：指向原始源文件的url数组。
names：可供个人引用的标识符数组映射。
sourceRoot:可选的。URL根，所有源都是相对的。
sourcesContent:可选的。原始源文件的内容数组。
mappings：包含实际映射的base64 vlq字符串。
file:可选的。与此源映射相关联的生成的文件名。

var consumer = new sourceMap.SourceMapConsumer(rawSourceMapJsonData);

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，禁用映射的验证它们是相加的。这可以提高性能，但应该与谨慎，作为最后的手段。即使这样，也应该避免使用这个标志运行测试，如果可能的话。
ignoreInvalidMapping:可选的。当 true，而不是抛出错误无效映射，它将被忽略。

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

SourceMapGenerator.fromSourceMap (sourceMapConsumer sourceMapGeneratorOptions)

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

sourceMapConsumer SourceMap。
sourceMapGeneratorOptions 选项，这些选项将被传递给SourceMapGenerator构造函数，该构造函数在底层使用。

var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer, {
  ignoreInvalidMapping: true,
});

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

var consumer = new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
var 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-js 共发布 9 个版本，首次发布于 2021/02/08；过去 12 个月发布了 1 个版本。

版本	发布日期	距今
`1.2.2`latest	2026/09/30	1 个月前
`1.2.1`	2024/09/09	2 年前
`1.2.0`	2024/03/20	2 年前
`1.1.0`	2024/03/18	2 年前
`1.0.3`	2024/03/18	2 年前
`1.0.2`	2022/01/19	4 年前

关于 source-map-js 的常见问题

source-map-js 是什么？

生成并使用源映射

如何安装 source-map-js？

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

source-map-js 支持 TypeScript 吗？

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

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

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

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

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

source-map-js 可以商用吗？

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

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

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

source-map-js 还在维护吗？

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