# @backtrace/javascript-cli 中文文档

规范地址：https://npmcn.com/package/%40backtrace/javascript-cli/

版本：0\.3\.2
npm 元数据更新时间：2026-10-29T17:17:18.473Z
中文译文更新时间：2026-11-07T15:23:55.395Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：164 kB，60 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14
- 运行依赖：5 个
- 首次发布：2023-10-30T13:14:25.214Z
- 最新版本发布：2024-01-03T16:08:10.969Z
- 近 30 天下载量：8961（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

回溯跟踪 CLI 用于 Javascript 文件的工作.

## 安装

```sh
npm install @backtrace/javascript-cli
```

也可以使用：`pnpm add @backtrace/javascript-cli`、`yarn add @backtrace/javascript-cli`、`bun add @backtrace/javascript-cli`

## README

# 回溯跟踪-js

用于管理 Javascript 文件的回溯跟踪工具 .

## 目录

1.  [说明](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-description)
2.  [使用量](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-usage)
    -   [`run`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-run)
    -   [`process`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-process)
    -   [`upload`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-upload)
    -   [`add-sources`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-add-sources)
    -   [全球备选方案](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-global-options)
    -   [配置文件](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-configuration-file)

# 说明

在使用源图的情况下调试已修改的应用程序是容易的. 他们也可以帮助改进你的报告 后寻. 这个工具有助于在源文件和源图文件中添加标识符,使 Backtrace 能够匹配源 源图.

来源的标识器将在运行时间进行处理,并附在回溯追踪报告后. 有了上传的源图, 回溯追踪可以将Calltack中的文件与可用的源图相匹配,并显示关于错误的额外信息.

# 使用量

在大多数情况下,你会想 [`process`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-process) 首先选择文件 [`add-sources`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-add-sources),然后则 [`upload`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-upload) 他们.

最好把这些命令添加到您的制作构建脚本中。 例如:

```jsonc
// package.json
{
    "scripts": {
        "build": "tsc && npm run backtrace:process && npm run backtrace:add-sources && npm run backtrace:upload",
        "backtrace:process": "npx backtrace-js process ./lib",
        "backtrace:add-sources": "npx backtrace-js add-sources ./lib",
        "backtrace:upload": "npx backtrace-js upload ./lib --url ..."
    }
}
```

`backtrace-js` 披露以下命令:

## `run`

执行所有命令的方便快捷键 。 执行命令顺序 :

1.  [`process`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-process)
2.  [`add-sources`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-add-sources)
3.  [`upload`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-upload)

### 选项

#### `--process`

运行 [`process`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-process) 命令.

#### `--add-sources`

运行 [`add-sources`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-add-sources) 命令.

#### `--upload`

运行 [`upload`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-upload) 命令.

#### `--dry-run`, (中文(简体) ), `-n`

将不会修改文件, 也不会上传它们 .

#### `<path>`, (中文(简体) ), `--path <string>`, (中文(简体) ), `-p <string>`

在提供的路径中搜索文件 。 这是默认位置参数 。 如果不提供,将在 当前目录.

#### `--force`, (中文(简体) ), `-f`

部队处理已处理的文件。 可能导致附加数据的重复.

#### `--pass-with-no-files`

默认, `run` 当找不到文件时, 将返回一个非零退出代码。 把这个递给0号.

#### `--output <string>`, (中文(简体) ), `-o <string>`

指定此选项将归档输出到文件, 而不是上传到 Backtrace 。 无法用于上传 .

#### `--url <string>`, (中文(简体) ), `-u <string>`

要上传源图的 URL 。 无法使用 `--subdomain`。 。 。 .

#### `--subdomain <string>`, (中文(简体) ), `-s <string>`

用于上传的子域 。 您还必须指定 `--token`。无法使用 `--url`。 。 。 .

**3⁄4 ̄ ̧漯B**:由于 URL 格式为 `https://submit.backtrace.io/{{subdomain}}/{{token}}/sourcemap`。 。 。 .

#### `--token <string>`, (中文(简体) ), `-t <string>`

用于上传 。 仅可用 `--subdomain`。 。 。 .

#### `--include-sources`

默认情况下,源图文件中的源将不会被上传到 Backtrace. 指定包含 `sourcesContent` 键入源图.

#### `--insecure`, (中文(简体) ), `-k`

禁用 HTTPS 证书检查 .

## `process`

将调试标识符添加到源码和源码映射文件。 在提供的路径及其中搜索源文件 使用相应的源图 `sourceMappingURL`。如果处理源,则跳出源.

源将有一个运行时间片断和 `debugId` 注释附于文件末尾。 何时 `//# debugId=#` 实值 目前,源图和源图被视为已处理。 由于运行时间片断抵消了源头 行,源图映射也会被更新.

原始图将 `debugId` 附于 JSON 对象.

### 选项

#### `<path>`, (中文(简体) ), `--path <string>`, (中文(简体) ), `-p <string>`

在提供的路径中搜索文件 。 这是默认位置参数 。 如果不提供,将在 当前目录.

#### `--dry-run`, (中文(简体) ), `-n`

结尾不会修改文件 。 用于显示命令的结果而不实际移动 来源.

#### `--force`, (中文(简体) ), `-f`

部队处理已处理的文件。 可能导致附加数据的重复.

#### `--pass-with-no-files`

默认, `process` 当找不到文件时, 将返回一个非零退出代码。 把这个递给0号.

### 实例

```sh
> backtrace-js process ./lib
> backtrace-js process ./lib/source1.js ./lib/source2.js
```

## `upload`

上传已处理的源图到 Backtrace 。 源图被拉链并发送到您的后端跟踪实例的符号 存储.

上传前请务必:

-   [`process`](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-process) 来源和出处图,
-   创建一个提交符号符号,
-   获取您的子域名或 URL 上传源图,

源图在 `debugId` 字段位于源图 JSON 对象.

### 创建符号提交符

要上传出源图, 您必须有一个提交符 :

1.  转到您的 Backtrace 实例, 并打开您想要上传源图的工程设置 .
2.  下 **符号**选择 **访问令牌**。 。 。 .
3.  复制或创建新符号访问符.

### 获取上传源图的子域名或 URL

如果您使用主机实例 Backtrace, 您很可能只需要通过子域名 。 你可以解决 您的实例地址的子域名.

例如,如果您的实例地址是 `https://example.sp.backtrace.io`,您的子域将是 `example`。 。 。 .

如果您出于某种原因无法通过这种方式上传URL, 或者您正在使用一个前提安装, 请检索 使用以下步骤的完整 URL .

_在 Backtrace.io 中复制 URL 的地方吗 ?_

#### 主办案件

如果你的病例是回溯追踪的 io, 您可以使用 `https://submit.backtrace.io/<your subdomain>/<submission token>/sourcemap`。如果您的实例被托管在 backtrace.io上, 您可以使用 `https://submit.backtrace.io/<your subdomain>/<submission token>/sourcemap`。 。 。 .

例如,对于子域 [https://example.sp.backtrace.io (英语)](https://example.sp.backtrace.io/)符号 `bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7`,则 URL 将是 `https://submit.backtrace.io/example/bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7/sourcemap`。 。 。 .

#### 假设

如果您实例是在前提下托管的, 您可以使用 `<your address>:6098//post?format=sourcemap&token=<submission token>`。 。 。 .

例如,关于地址 [https://backtrace.example.com (中文(中国大陆) )](https://backtrace.example.com/)符号 `bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7`,则 URL 将是 `https://backtrace.example.com:6098//post?format=sourcemap&token=bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7`。 。 。 .

### 选项

#### `<path>`, (中文(简体) ), `--path <string>`, (中文(简体) ), `-p <string>`

在提供的路径中搜索文件 。 这是默认位置参数 。 如果不提供,将在 当前目录.

#### `--url <string>`, (中文(简体) ), `-u <string>`

要上传源图的 URL 。 无法使用 `--subdomain`。 。 。 .

#### `--subdomain <string>`, (中文(简体) ), `-s <string>`

用于上传的子域 。 您还必须指定 `--token`。无法使用 `--url`。 。 。 .

**3⁄4 ̄ ̧漯B**:由于 URL 格式为 `https://submit.backtrace.io/{{subdomain}}/{{token}}/sourcemap`。 。 。 .

#### `--token <string>`, (中文(简体) ), `-t <string>`

用于上传 。 仅可用 `--subdomain`。 。 。 .

#### `--include-sources`

默认情况下,源图文件中的源将不会被上传到 Backtrace. 指定包含 `sourcesContent` 键入源图.

#### `--insecure`, (中文(简体) ), `-k`

禁用 HTTPS 证书检查 .

#### `--dry-run`, (中文(简体) ), `-n`

将不会在结尾上传文件 。 用于显示命令的结果而不实际上传 源图.

#### `--force`, (中文(简体) ), `-f`

即使没有处理上传文件 .

#### `--pass-with-no-files`

默认, `upload` 当找不到文件时, 将返回一个非零退出代码。 把这个递给0号.

#### `--output <string>`, (中文(简体) ), `-o <string>`

指定此选项将归档输出到文件, 而不是上传到 Backtrace 。 无法用于上传 .

### 实例

```
> backtrace-js upload --subdomain example --token bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7
> backtrace-js upload ./lib --url https://submit.backtrace.io/example/bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7/sourcemap
> backtrace-js upload ./lib/index.js.map -o archive.zip
```

## `add-sources`

如果您的构建工具不包括源图中的原始源, 您可以使用此命令添加 源到上传前的源图。 确定上传方式 `--include-sources`如果源图已经存在 `sourcesContent`,它会被跳过.

资源将来自 `sources` 相对于源映射位置的数组,或 `sourceRoot` 在图出处, 如果提供.

### 选项

#### `<path>`, (中文(简体) ), `--path <string>`, (中文(简体) ), `-p <string>`

在提供的路径中搜索文件 。 这是默认位置参数 。 如果不提供,将在 当前目录.

#### `--dry-run`, (中文(简体) ), `-n`

结尾不会修改文件 。 用于显示命令的结果而不实际修改文件 .

#### `--force`, (中文(简体) ), `-f`

处理文件, 即使源Content不是空的 。 将覆盖现有来源 .

#### `--pass-with-no-files`

默认, `add-sources` 当找不到文件时, 将返回一个非零退出代码。 把这个递给0号.

### 实例

```
> backtrace-js add-sources ./lib
> backtrace-js add-sources ./lib/index.js.map ./lib/other.js.map
```

## 全球备选方案

所有命令共享以下选项:

#### `--help`, (中文(简体) ), `-h`

显示当前命令的帮助消息 .

#### `--verbose`, (中文(简体) ), `-v`

维博斯级. -v打印调试日志, -vv打印全部日志.

#### `--quiet`, (中文(简体) ), `-q`

禁用所有日志信息 .

#### `--log-level <string>`

设置日志级别。 可以是: `quiet`, (中文(简体) ), `error`, (中文(简体) ), `warn`, (中文(简体) ), `info`, (中文(简体) ), `debug`, (中文(简体) ), `verbose`默认 : `info`。 。 。 .

#### `--config <string>`

配置文件的路径 。 见 [配置文件](https://npmcn.com/package/%40backtrace/javascript-cli/#readme-configuration-file) 更多细节.

## 配置文件

所有命令都可以从配置文件中读取. 默认情况下,配置从 `.backtracejsrc` 文档。 这个 文件应该有一个带有注释的 JSON (`jsonc`结构.

配置对象可以定义每个命令选项的值. 选择必须采用全名, 无前缀 `--`。 。 。 .

您可以在对象中使用命令名称设置每个特定命令的选项并传递选项.

文件实例 :

```jsonc
{
    // Paths used by all commands
    "path": ["./lib", "./dist"],
    "upload": {
        // Path used only by the upload command
        "path": "./output",
        "insecure": true,
        "url": "https://submit.backtrace.io/example/bebbbc8b2bdfac76ad803b03561b25a44039e892ffd3e0beeb71770d08e2c8a7/sourcemap"
    },
    "add-sources": {
        "force": true
    },
    "run": {
        "process": true,
        "add-sources": false,
        "upload": true
    }
}
```

全球备选方案 **无法** 在配置文件中设置.

## 常见问题

### @backtrace/javascript-cli 是什么？

回溯跟踪 CLI 用于 Javascript 文件的工作\.

### 如何安装 @backtrace/javascript-cli？

在项目目录运行 npm install @backtrace/javascript-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 backtrace-js，可以用 npx backtrace-js 直接运行。

### @backtrace/javascript-cli 支持 TypeScript 吗？

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

### @backtrace/javascript-cli 支持 ESM 还是 CommonJS？

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

### @backtrace/javascript-cli 需要什么版本的 Node\.js？

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

### @backtrace/javascript-cli 可以商用吗？

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

### @backtrace/javascript-cli 的下载量有多少？

根据 npm 官方下载统计，@backtrace/javascript-cli 在 2026/10/08 – 2026/11/06 这 30 天内被下载 8,961 次，日均约 299 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @backtrace/javascript-cli 还在维护吗？

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