# @appland/appmap-agent-js 中文文档

规范地址：https://npmcn.com/package/%40appland/appmap-agent-js/

版本：14\.2\.0
npm 元数据更新时间：2024-03-15T16:17:44.801Z
中文译文更新时间：2026-11-08T05:39:20.303Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40appland/appmap-agent-js
原文对照：https://npmcn.com/package/%40appland/appmap-agent-js/?lang=original
项目主页：https://github.com/getappmap/appmap-agent-js.git/#readme
源码仓库：https://github.com/getappmap/appmap-agent-js

弃用说明：This package has been deprecated\. Please use appmap-node instead

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

- 包体积（解压后）：1.7 MB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：16\.x\.x \|\| 17\.x\.x \|\| 18\.x\.x \|\| 19\.x\.x
- 运行依赖：21 个
- 首次发布：2021-03-30T10:28:25.405Z
- 最新版本发布：2023-08-16T14:19:35.062Z
- 近 30 天下载量：1885（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：171（近 12 个月 0 个）

## 中文简介

`appmap-agent-js` 是 JavaScript 记录代理 [应用程序](https://appmap.io/) 框架.

## 安装

```sh
npm install @appland/appmap-agent-js
```

也可以使用：`pnpm add @appland/appmap-agent-js`、`yarn add @appland/appmap-agent-js`、`bun add @appland/appmap-agent-js`

## README

# 开始 `appmap-agent-js`

`appmap-agent-js` 是 JavaScript 记录代理 [应用程序](https://appmap.io/) 框架.

## 导言

`appmap-agent-js` 运行时从 Node.js 进程记录 AppMaps 。 记录 AppMaps 有几种策略:

1.  记录测试案例。 目前,我们支持 [欢笑](https://jestjs.io/) 财务报告和审定财务报表 [摩卡岛](https://mochajs.org/)。 。 。 .
2.  通过 http 调用网络端点来记录使用起/止控的Node.js进程. 这些由AppMap代理执行,让用户远程控制录音.
3.  记录从开始到完成的节点.js进程.

## 安装和设置

### 所需资源

支持的平台 :

-   主流 os: Linux distros, macOS, and Windows. 星洲网.
-   节点(Node.js):任何没有被淘汰的更新的主要版本 -- -- 即:16,18,和19.
-   快报.js: 4.
-   git是极好的建议.
-   需要mocha QQ 8.0.0从测试案例录入 AppMaps(早期版本不支持所需的根钩).
-   jest qq 25,更旧的版本也可能有用,但还没有经过测试.

**请 [打开新的 GitHub 票](https://github.com/getappmap/appmap-agent-js/issues/new) 如果您的申请不符合标准,或与代理人有任何问题.**

### 安装

在您的 Node.js 工程文件夹中运行此命令( 在哪里) `package.json` 地点:

```sh
npx @appland/appmap install
```

您将遵循一系列安装和配置代理的步骤.

或者,可以将代理设备作为普通设备直接安装 [npm 软件包](https://www.npmjs.com/package/@appland/appmap-agent-js)数字 :

```sh
npm install --save-dev @appland/appmap-agent-js
```

为了使用远程录音,并查看和与录制的 AppMaps 交互,我们建议为流行代码编辑器安装 AppMap 扩展:

-   [VS 代码中的 AppMap 市场](https://marketplace.visualstudio.com/items?itemName=appland.appmap)
-   [JetBrains市场中的 AppMap](https://plugins.jetbrains.com/plugin/16701-appmap)

### 配置

代理从命名的文件读取配置选项 `appmap.yml`。如果此文件不存在,将创建默认文件。 注意 `install` 命令创建合适的 `appmap.yml` 通过扫描工程目录来创建文件。 我们建议你们审查任何产生 `appmap.yml` 文档并确认您的应用程序名称和将记录的目录列表.

**用于 JavaScript 源地图的项目**: 向要记录的源添加路径。 例如:

```yaml
name: MyApp
packages:
  - path: src/server/controllers
  - path: src/server/data
  - path: src/server/lib
  - path: src/server/models
  - path: src/server/routes
```

**没有 JavaScript 源地图的项目**: 包括构建文件夹。 例如:

```yaml
name: MyApp
packages:
  - path: dist/controllers
  - path: dist/data
  - path: dist/lib
  - path: dist/models
  - path: dist/routes
```

如果您不确定要选择哪个选项, 请从源头开始, 并创建文件夹并优化 `appmap.yml` 稍后存档.

## 记录 AppMaps 中

一次 `appmap.yml` 已配置到您的项目, 您已准备好录制 AppMps .

### 记录测试案例 :

1.  验证测试是否在 AppMaps 记录前运行 .
2.  测试命令的前缀 `npx appmap-agent-js --` 例如:

```sh
npx appmap-agent-js -- mocha 'test/**/*.ts'
```

**`npm run test` 目前只支持直接引用测试框架** 3个. `appmap-agent-js` 将运行测试。 测试完成后, AppMaps 将被存储在默认输出目录中 `tmp/appmap/(mocha|jest)`。 。 。 .

### 用远程记录记录节点.js进程:

1.  将节点命令前缀为 `npx appmap-agent-js --recorder=remote --`。例如:

```sh
npx appmap-agent-js --recorder=remote -- node app/main.js --param1 hello --param2=world
```

2.  `appmap-agent-js` 将启动应用程序并输入其 http 堆栈。 它会听 [远程记录请求](https://appland.com/docs/reference/remote-recording) 在应用程序的所有 http 端口上.
3.  启动远程记录 :
    -   [在VS代码中](https://appland.com//docs/reference/remote-recording#visual-studio-code)
    -   [在 JetBrains IDES 中](https://appland.com/docs/reference/remote-recording#jetbrains-intellij-pycharm-rubymine)
    -   [带卷曲](https://appland.com/docs/reference/remote-recording.html#remote-recording-api)
4.  与您的应用程序或服务进行交互,以练习包含的代码 `appmap.yml`
5.  停止录音,将新的 AppMap 保存到磁盘中.

### 从开始到完成记录节点.js进程

1.  将节点命令前缀为 `npx appmap-agent-js --recorder=process --`。例如:

```sh
npx appmap-agent-js --recorder=process -- node app/main.js --arg1 val1 --arg2=val2
```

2.  当节点进程退出时,将存储一个 AppMap `tmp/appmap/process`。 。 。 .

## 正在查看 AppMaps

已录制的 AppMap 保存为 `.appmap.json` 项目文件夹中的文件(默认位置 : `tmp/appmap`) (中文(简体) ).

跟踪您的 IDE 文档打开记录 `.appmap.json` 文件 :

-   [在VS代码中](https://appland.com/docs/reference/vscode)
-   [在 JetBrains IDES 中](https://appland.com/docs/reference/jetbrains)

## 常用参数

使用次数最多的 `appmap-agent-js` 参数为:

-   `--recorder=[mocha|jest|remote|process]`: 进程记录器
    -   从起始命令推断出默认记录器 :
        -   `mocha` 如果命令包含 `mocha`
        -   `jest` 如果命令包含 `jest`
        -   `process` 在所有其他情况下
    -   `mocha` 财务报告和审定财务报表 `jest` 记录器将 AppMaps 从测试大小写自动记录
    -   `remote` 记录器必须用 http 请求手动启动并停止
    -   `process` 从头到尾自动记录整个进程
        -   **警告:** AppMaps 记录在 `process` 录音机可能过于庞大和吵闹.
-   `--command="_start command_"`: 指定应用程序启动命令或测试启动命令的替代方法,用引号包起来
-   `--log-level=[debug|info|warning|error]`: 默认为 `info`
-   `--log-file=_file_`: 日志文件的位置, 默认为 `stderr`
-   `--appmap-dir=_directory_`: 记录的 AppMap 文件的位置,默认为 `tmp/appmap`。 。 。 .

### 示例

```
npx appmap-agent-js --recorder=mocha --command='mocha "test/**/*.ts"' --log-level=error
```

## 今后的步骤

-   [appmap-agent-js 参考文件](https://appland.com/docs/reference/appmap-agent-js.html)

## 常见问题

### @appland/appmap-agent-js 是什么？

appmap-agent-js 是 JavaScript 记录代理 应用程序 框架\.注意：该包已被作者标记为弃用——This package has been deprecated\. Please use appmap-node instead

### 如何安装 @appland/appmap-agent-js？

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

### @appland/appmap-agent-js 支持 TypeScript 吗？

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

### @appland/appmap-agent-js 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @appland/appmap-agent-js 需要什么版本的 Node\.js？

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

### @appland/appmap-agent-js 可以商用吗？

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

### @appland/appmap-agent-js 的下载量有多少？

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

### @appland/appmap-agent-js 还在维护吗？

最新版本 14\.2\.0 发布于 2023/08/16（3 年前）；至今共发布 171 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/03/30。作者已将其标记为弃用，新项目建议寻找替代方案。