# convert-source-map 中文文档

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

版本：2\.0\.0
npm 元数据更新时间：2023-07-09T22:05:41.150Z
中文译文更新时间：2026-11-04T13:44:36.100Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：15.9 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2013-03-13T13:03:57.455Z
- 最新版本发布：2022-10-17T22:06:48.628Z
- 近 30 天下载量：898209868（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 0 个）

## 中文简介

将源映射从/转换为不同的格式，并允许添加/更改属性。

## 安装

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

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

## README

# convert-source-map [![Build Status](https://img.shields.io/github/workflow/status/thlorenz/convert-source-map/CI?style=flat-square)](https://github.com/thlorenz/convert-source-map/actions?query=workflow:ci)

将源映射从/转换为不同的格式，并允许添加/更改属性。

```js
var convert = require('convert-source-map');

var json = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .toJSON();

var modified = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .setProperty('sources', [ 'SRC/FOO.JS' ])
  .toJSON();

console.log(json);
console.log(modified);
```

```json
{"version":3,"file":"build/foo.min.js","sources":["src/foo.js"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
{"version":3,"file":"build/foo.min.js","sources":["SRC/FOO.JS"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
```

## 升级

在v2.0.0之前， `fromMapFileComment` 和 `fromMapFileSource` 函数接受一个String目录路径，并使用该路径从文件系统中解析和读取源映射文件。然而，这使得该库仅限于nodejs环境，并破坏了带有查询字符串的源代码。

在v2.0.0中，现在需要传递一个函数来读取文件。它将以字符串的形式接收源文件名，您可以将其解析为文件系统路径、URL或其他任何内容。

如果你正在使用 `convert-source-map` 在nodejs中，如果你想要之前的行为，你可以使用这样的函数：

```diff
+ var fs = require('fs'); // Import the fs module to read a file
+ var path = require('path'); // Import the path module to resolve a path against your directory
- var conv = convert.fromMapFileSource(css, '../my-dir');
+ var conv = convert.fromMapFileSource(css, function (filename) {
+   return fs.readFileSync(path.resolve('../my-dir', filename), 'utf-8');
+ });
```

## API

### fromObject (obj)

从给定对象返回源映射转换器。

### fromJSON (json)

从给定的json字符串返回源映射转换器。

### fromURI (uri)

从给定uri编码的json字符串返回源映射转换器。

### fromBase64 (base64)

从给定的base64编码json字符串返回源映射转换器。

### fromComment(评论)

从给定的base64或uri编码的json字符串返回源映射转换器 `//# sourceMappingURL=...`。

### readMap fromMapFileComment(评论)

从给定返回源映射转换器 `filename` 通过解析 `//# sourceMappingURL=filename`。

`readMap` 必须是一个函数，它接收源映射文件名并返回源映射的String或Buffer（如果同步读取），或 `Promise` 包含源映射的String或Buffer（如果异步读取）。

如果 `readMap` 不返回a `Promise`， `fromMapFileComment` 将同步返回源映射转换器。

如果 `readMap` 返回一个 `Promise`， `fromMapFileComment` 也会返回 `Promise`。这个 `Promise` 将被源映射转换器解决，或者被错误拒绝。

#### 例子

**Node.js中的同步读取：**

```js
var convert = require('convert-source-map');
var fs = require('fs');

function readMap(filename) {
  return fs.readFileSync(filename, 'utf8');
}

var json = convert
  .fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
  .toJSON();
console.log(json);
```

**Node.js中的异步读取：**

```js
var convert = require('convert-source-map');
var { promises: fs } = require('fs'); // Notice the `promises` import

function readMap(filename) {
  return fs.readFile(filename, 'utf8');
}

var converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
```

**在浏览器中异步读取：**

```js
var convert = require('convert-source-map');

async function readMap(url) {
  const res = await fetch(url);
  return res.text();
}

const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
```

### fromSource(源)

查找文件中的最后一个源映射注释并返回源映射转换器或返回 `null` 如果没有找到源映射注释。

### readMap fromMapFileSource(源)

查找文件中的最后一个源映射注释并返回源映射转换器或返回 `null` 如果没有找到源映射注释。

`readMap` 必须是一个函数，它接收源映射文件名并返回源映射的String或Buffer（如果同步读取），或 `Promise` 包含源映射的String或Buffer（如果异步读取）。

如果 `readMap` 不返回a `Promise`， `fromMapFileSource` 将同步返回源映射转换器。

如果 `readMap` 返回一个 `Promise`， `fromMapFileSource` 也会返回 `Promise`。这个 `Promise` 将被源映射转换器解决，或者被错误拒绝。

### toObject ()

返回基础源映射的副本。

### toJSON((空间))

将源映射转换为json字符串。如果 `space` 是给定的（可选），这将传递给 [JSON.stringify](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify) 当 生成JSON字符串。

### toURI ()

将源映射转换为uri编码的json字符串。

### toBase64 ()

将源映射转换为base64编码的json字符串。

### toComment(\[选项\])

将源映射转换为可附加到源文件的内联注释。

默认情况下，注释的格式如下： `//# sourceMappingURL=...`，你会 通常可以在JS源文件中看到。

当 `options.encoding == 'uri'`，则数据将被uri编码，否则将被base64编码。

当 `options.multiline == true`，注释的格式如下： `/*# sourceMappingURL=... */`，可以在CSS源文件中找到。

### addProperty(关键字,值)

将给定的属性添加到源映射。如果属性已经存在，则抛出错误。

### setProperty(关键字,值)

将给定的属性设置为源映射。如果属性不存在，则添加它，否则更新它的值。

### getProperty(键)

获取源映射的给定属性。

### removeComments (src)

返回 `src` 删除所有源映射注释

### removeMapFileComments (src)

返回 `src` 删除所有指向映射文件的源映射注释。

### commentRegex

提供了 **一个新鲜的** 每次访问时使用RegExp。可以用来查找源映射注释。

将源映射注释分成几个组：1：媒体类型，2:MIME类型，3：字符集，4：编码，5：数据。

### mapFileCommentRegex

提供了 **一个新鲜的** 每次访问时使用RegExp。可以用来查找指向映射文件的源映射注释。

### \[选项\]generateMapFileComment(文件)

返回链接到外部源映射的注释 `file`。

默认情况下，注释的格式如下： `//# sourceMappingURL=...`通常会在JS源文件中看到。

当 `options.multiline == true`，注释的格式如下： `/*# sourceMappingURL=... */`，可以在CSS源文件中找到。

## 常见问题

### convert-source-map 是什么？

将源映射从/转换为不同的格式，并允许添加/更改属性。

### 如何安装 convert-source-map？

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

### convert-source-map 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/convert-source-map 是否存在。

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

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

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

convert-source-map 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

最新版本 2\.0\.0 发布于 2022/10/18（4 年前）；至今共发布 36 个版本，其中过去 12 个月发布了 0 个；首次发布于 2013/03/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。