# @jest/source-map 中文文档

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

版本：30\.5\.2
npm 元数据更新时间：2026-09-18T13:59:40.154Z
中文译文更新时间：2026-11-05T16:30:11.001Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：36.6 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^18\.14\.0 \|\| ^20\.0\.0 \|\| ^22\.0\.0 \|\| \>=24\.0\.0
- 运行依赖：4 个
- 首次发布：2019-03-05T14:46:21.517Z
- 最新版本发布：2026-09-18T13:59:39.969Z
- 近 30 天下载量：216266136（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 2 个）

## 中文简介

应用源地图来堆叠痕迹,所以一个失败的测试点在您写的代码上而不是在代码Jest运行上.

## 安装

```sh
npm install @jest/source-map
```

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

## README

# @ jest/ source- map (英语)

应用源地图来堆叠痕迹,所以一个失败的测试点在您写的代码上而不是在代码Jest运行上.

这是杰斯特内部使用的模块. 它的存在是因为 `--enable-source-maps` 财务报告和审定财务报表 `module.setSourceMapsSupport()` 不覆盖编译的代码 `vm`,这是杰斯评价测试文件的方式,并且因为节点无法注册一个文件名的地图——杰斯服务地图来自自己的变换管道,而不是来自 `sourceMappingURL` 磁盘上的评论.

## 安装

```sh
$ npm install --save @jest/source-map
```

## API 密码

### `SourceMapSupport#install(sourceMaps?: SourceMapRegistry | null, options?: SourceMapSupportInstallOptions): void`

替换 `Error.prepareStackTrace` 在当前范围内,读取 `.stack` 在任何错误上使框架与原始来源相对应. `jest-runner` 拥有每个工人一个实例,每个测试文件安装一次.

`sourceMaps` 将已转换的文件映射到 `.map` 文件 Jest 写入了它的变换缓存——在 Jest 内部, `runtime.getSourceMaps()`编辑 `sources` 内有 URL 语义的地图解析度与已转换的文件相对,而不是与地图本身的位置相对. 登记册中缺失的文件返回到 `sourceMappingURL` 对文件本身进行评论,该文件涵盖预先编译的输出,用于运送自己的地图.

```javascript
import {SourceMapSupport} from '@jest/source-map';

const sourceMapSupport = new SourceMapSupport();
sourceMapSupport.install(new Map([['/build/app.js', '/cache/app.js.map']]));

new Error('boom').stack;
// Error: boom
//     at greet (/src/app.ts:12:9)
```

物料在过程的寿命期间会被安装,每个调用交换都会被安装在新的登记册中. 无事被还原,是故意的:在测试完成后所抛出的一个错误——一个出错的计时器,一个浮出水面的承诺——是用户最难安排的时间,否则它就会在被转换的文件中报告一个位置.

无法解析的地图通过 `console.warn`; 通过 `{suppressWarnings: true}` 关掉它.

### `SourceMapSupport#getCallsite(level: number, sourceMaps?: SourceMapRegistry | null): CallSite`

返回一个已重映射 [`CallSite`](https://v8.dev/docs/stack-trace-api#customizing-stack-traces), (中文(简体) ), `level` 在呼叫器上方的帧。 用于 `--testLocationInResults`。将其解析的地图与已安装的处理器共享,因此 `.map` 文件读取一次.

### `getCallsite(level: number, sourceMaps?: SourceMapRegistry | null): CallSite`

折旧的自由功能别名 `SourceMapSupport#getCallsite`。 。 。 .

### `SourceMapRegistry`

`Map<string, string>` ——将文件路径转换为源地图路径.

## 为可读性选择函数名称,而非光谱

框架以源地图命名 `name` 在画框 **拥有** 立场。 这个名字是标识符 _调用_ 而不是附加功能,所以每个框架都用其线上的呼声附加注释:

```
at Object.toBeTruthy (assertionCount.test.js:12:17)
at Object.setTimeout (inside.js:9:3)
```

光谱校正读取名称 _电话_ 换成位置。 这是什么 [`source-map-support@0.5.14`](https://github.com/evanw/node-source-map-support/pull/253) 切换到,它会折叠上面的帧到 `Object.<anonymous>`,因为V8对于模块级框架没有自己的名称. 无论是哪种方式,位置都是一样的——只有名字不同,并且只有V8不能命名帧的地方.

这个包对读取测试失败的选择,所以保留了注释. 如果你需要谱面语义, `getCallsite` 手举起 `CallSite` 你可以自己地图.

## 常见问题

### @jest/source-map 是什么？

应用源地图来堆叠痕迹,所以一个失败的测试点在您写的代码上而不是在代码Jest运行上\.

### 如何安装 @jest/source-map？

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

### @jest/source-map 支持 TypeScript 吗？

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

### @jest/source-map 支持 ESM 还是 CommonJS？

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

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

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

### @jest/source-map 可以商用吗？

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

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

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

### @jest/source-map 还在维护吗？

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