# @jridgewell/remapping 中文文档

规范地址：https://npmcn.com/package/%40jridgewell/remapping/

版本：2\.3\.5
npm 元数据更新时间：2025-08-12T06:43:35.514Z
中文译文更新时间：2026-11-04T20:32:45.086Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40jridgewell/remapping
原文对照：https://npmcn.com/package/%40jridgewell/remapping/?lang=original
项目主页：https://github.com/jridgewell/sourcemaps/tree/main/packages/remapping
源码仓库：https://github.com/jridgewell/sourcemaps

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

- 包体积（解压后）：59.4 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-06-29T21:44:02.256Z
- 最新版本发布：2025-08-12T06:43:35.321Z
- 近 30 天下载量：627966014（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

通过转换重新映射顺序源映射，以指向原始源代码

## 安装

```sh
npm install @jridgewell/remapping
```

也可以使用：`pnpm add @jridgewell/remapping`、`yarn add @jridgewell/remapping`、`bun add @jridgewell/remapping`

## README

# @jridgewell /重新映射

> 通过转换重新映射顺序源映射，以指向原始源代码

重新映射允许您获取通过转换代码和“重新映射”生成的源映射。 他们到原来的源位置。想想“我的迷你代码，用巴别塔转换和捆绑” 使用webpack"，所有指向原始源代码中的正确位置。

通过重新映射，您的源代码转换都不需要知道输入的源映射， 它们只需要生成一个输出源映射。这极大地简化了构建自定义 转换（考虑查找和替换）。

## 安装

```sh
npm install @jridgewell/remapping
```

## 用法

```typescript
function remapping(
  map: SourceMap | SourceMap[],
  loader: (file: string, ctx: LoaderContext) => (SourceMap | null | undefined),
  options?: { excludeContent: boolean, decodedMappings: boolean }
): SourceMap;

// LoaderContext gives the loader the importing sourcemap, tree depth, the ability to override the
// "source" location (where child sources are resolved relative to, or the location of original
// source), and the ability to override the "content" of an original source for inclusion in the
// output sourcemap.
type LoaderContext = {
 readonly importer: string;
 readonly depth: number;
 source: string;
 content: string | null | undefined;
}
```

`remapping` 接受最终的输出源映射和 `loader` 函数。对于每个源文件指针 在源映射中， `loader` 将使用已解析的路径调用。如果路径本身表示 转换后的文件（它有一个与之关联的源映射），然后是 `loader` 应该返回 sourcemap。如果没有，路径将被视为原始的、未转换的源代码。

```js
// Babel transformed "helloworld.js" into "transformed.js"
const transformedMap = JSON.stringify({
  file: 'transformed.js',
  // 1st column of 2nd line of output file translates into the 1st source
  // file, line 3, column 2
  mappings: ';CAEE',
  sources: ['helloworld.js'],
  version: 3,
});

// Uglify minified "transformed.js" into "transformed.min.js"
const minifiedTransformedMap = JSON.stringify({
  file: 'transformed.min.js',
  // 0th column of 1st line of output file translates into the 1st source
  // file, line 2, column 1.
  mappings: 'AACC',
  names: [],
  sources: ['transformed.js'],
  version: 3,
});

const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    // The "transformed.js" file is an transformed file.
    if (file === 'transformed.js') {
      // The root importer is empty.
      console.assert(ctx.importer === '');
      // The depth in the sourcemap tree we're currently loading.
      // The root `minifiedTransformedMap` is depth 0, and its source children are depth 1, etc.
      console.assert(ctx.depth === 1);

      return transformedMap;
    }

    // Loader will be called to load transformedMap's source file pointers as well.
    console.assert(file === 'helloworld.js');
    // `transformed.js`'s sourcemap points into `helloworld.js`.
    console.assert(ctx.importer === 'transformed.js');
    // This is a source child of `transformed`, which is a source child of `minifiedTransformedMap`.
    console.assert(ctx.depth === 2);
    return null;
  }
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };
```

在这个例子中， `loader` 将被调用两次：

1.  `"transformed.js"`中的第一个源文件指针 `minifiedTransformedMap`． 我们返回 它的关联源映射（毕竟它是一个转换后的文件），以便源映射位置可以 通过它跟踪到它所代表的源文件。
2.  `"helloworld.js"`，我们原始的，未经修改的源代码。这个文件没有源映射，所以 我们返回 `null`。

这个 `remapped` 源地图现在指向 `transformed.min.js` 进入各个位置 `helloworld.js`。如果 你要读 `mappings`，它表示“第一行的第0列输出行指向第1列。 文件第二行的列 `helloworld.js`＂．

### 一个文件的多个转换

为了方便起见，如果一个文件有多个单源转换，可以传递一个 源地图文件的数组，按照最近的转换源地图的顺序排列。请注意 改变了 `importer` 和 `depth` 对加载器的每个调用。所以上面的例子可以是 写为:

```js
const remapped = remapping(
  [minifiedTransformedMap, transformedMap],
  () => null
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };
```

### 加载图形的高级控制

#### `source`

这个 `source` 属性可以重写为任何值，以更改当前加载的位置。例如, 对于原始源文件，它允许我们更改原始源文件的位置 sourcemap源条目所表示的内容。对于已转换的文件，它允许我们更改 加载源映射的子源的相对解析位置。

```js
const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // We pretend the transformed.js file actually exists in the 'src/' directory. When the nested
      // source files are loaded, they will now be relative to `src/`.
      ctx.source = 'src/transformed.js';
      return transformedMap;
    }

    console.assert(file === 'src/helloworld.js');
    // We could futher change the source of this original file, eg, to be inside a nested directory
    // itself. This will be reflected in the remapped sourcemap.
    ctx.source = 'src/nested/transformed.js';
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sources: ['src/nested/helloworld.js'],
// };
```

#### `content`

这个 `content` 属性可以在遇到原始源文件时重写。例如，这允许 您必须手动提供原始文件的源内容，而不管是否 `sourcesContent` 字段存在于父源映射中。也可以设置为 `null` 删除 源内容。

```js
const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // transformedMap does not include a `sourcesContent` field, so usually the remapped sourcemap
      // would not include any `sourcesContent` values.
      return transformedMap;
    }

    console.assert(file === 'helloworld.js');
    // We can read the file to provide the source content.
    ctx.content = fs.readFileSync(file, 'utf8');
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sourcesContent: [
//     'console.log("Hello world!")',
//   ],
// };
```

### 选项

#### excludeContent

默认情况下, `excludeContent` 是 `false`． 通过 `{ excludeContent: true }` 将排除 `sourcesContent` 字段从返回的源映射。这在你想减少的时候很有用 源地图的大小。

#### decodedMappings

默认情况下, `decodedMappings` 是 `false`． 通过 `{ decodedMappings: true }` 将离开 `mappings` 字段中 [解码状态](https://github.com/rich-harris/sourcemap-codec) 而不是 编码成VLQ字符串。

## 常见问题

### @jridgewell/remapping 是什么？

通过转换重新映射顺序源映射，以指向原始源代码

### 如何安装 @jridgewell/remapping？

在项目目录运行 npm install @jridgewell/remapping，或使用 pnpm add / yarn add / bun add。

### @jridgewell/remapping 支持 TypeScript 吗？

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

### @jridgewell/remapping 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @jridgewell/remapping 可以商用吗？

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

### @jridgewell/remapping 的下载量有多少？

根据 npm 官方下载统计，@jridgewell/remapping 在 2026/10/05 – 2026/11/03 这 30 天内被下载 627,966,014 次，日均约 20,932,200 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @jridgewell/remapping 还在维护吗？

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