# @elastic/synthetics 中文文档

规范地址：https://npmcn.com/package/%40elastic/synthetics/

版本：1\.30\.0
npm 元数据更新时间：2026-11-12T17:17:47.122Z
中文译文更新时间：2026-11-13T10:41:55.369Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.2 MB，283 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：23 个
- 首次发布：2020-10-29T21:06:15.427Z
- 最新版本发布：2026-11-12T17:17:46.753Z
- 近 30 天下载量：109525（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：115（近 12 个月 18 个）

## 中文简介

弹性合成监测剂

## 安装

```sh
npm install @elastic/synthetics
```

也可以使用：`pnpm add @elastic/synthetics`、`yarn add @elastic/synthetics`、`bun add @elastic/synthetics`

## README

[![ci](https://github.com/elastic/synthetics/actions/workflows/ci.yml/badge.svg)](https://github.com/elastic/synthetics/actions/workflows/ci.yml) [![e2e](https://github.com/elastic/synthetics/actions/workflows/e2e.yml/badge.svg)](https://github.com/elastic/synthetics/actions/workflows/e2e.yml)

# 合成代理

与 Real 浏览器合成监测.

## 使用量

安装软件包

```sh
npm install -g @elastic/synthetics
```

通过CLI运行套房

```
npx @elastic/synthetics [options] [dir] [files] file
```

使用 `--workdir /path/to/scratch` 为运行时间缓存选择可写目录 文档,包括截图和临时按键。 方案 等值为 `run({ workdir: '/path/to/scratch' })`相对路径 工作目录。 默认是 `.synthetics` 在当前工作目录中. 合成器创建和去除一个进程特定的子目录(`<workdir>/<pid>`, (中文(简体) ), 工作目录本身保持不变。 用于推,使用 `npx @elastic/synthetics push --workdir /path/to/scratch`; 捆绑在 `<workdir>/bundles` 并在成功捆绑后删除子目录. 项目发现和配置分辨率不受影响。 打电话的人必须 为运行合成器的用户提供写入权限; 合成不会改变现有目录上的所有权或权限.

## 浏览器行程

默认 `journey()` DSL通过 Playwright 发射一个真正的 Chromium 浏览器 当您想要验证用户成像流程时, 是正确的选择 .

```ts
import { journey, step, expect } from '@elastic/synthetics';

journey('homepage loads', ({ page, params }) => {
  step('open', async () => {
    await page.goto(params.url);
  });
  step('check title', async () => {
    expect(await page.title()).toContain('Welcome');
  });
});
```

## API 行程( 无浏览器)

仅用于 API 检查, 使用 `apiJourney()`它运行时没有启动浏览器, 这使得它适合OAuth保护的终点,多步API流量, 和高频轻量级监测.

```ts
import { apiJourney, monitor, step, expect } from '@elastic/synthetics';

apiJourney('orders API health', ({ request, params }) => {
  monitor.use({ schedule: 1, locations: ['us_east'] });

  let token: string;
  step('obtain OAuth2 token', async () => {
    const r = await request.post(`${params.authUrl}/oauth2/token`, {
      form: {
        grant_type: 'client_credentials',
        client_id: params.clientId,
        client_secret: params.clientSecret,
      },
    });
    expect(r.status()).toBe(200);
    token = (await r.json()).access_token;
  });

  step('check /orders', async () => {
    const r = await request.get(`${params.apiUrl}/orders`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    expect(r.status()).toBe(200);
  });
});
```

API 大部分的常规行程 `journey()` 水面- `step()`, (中文(简体) ), `expect`, (中文(简体) ), `params`, (中文(简体) ), `monitor.use()`, (中文(简体) ), `apiJourney.skip` 编号 : `apiJourney.only` ——整合 同样的 `push` 命令。 他们被推到基巴纳 `api`\- 类型监视器.

每个API的旅程都各自孤立 `APIRequestContext` 独立 cookie 罐;在一个旅程中设置的cookie在另一个旅程中不可见. 全体 `playwrightOptions` (单位:千美元)`baseURL`, (中文(简体) ), `extraHTTPHeaders`, (中文(简体) ), `ignoreHTTPSErrors`, (中文(简体) ), `httpCredentials`、客户端证书、代理等) 隐藏 Playwright API 上下文 .

按请求的网络数据——URL,方法,状态,标题,体积,时间, 和(对于HTTPS)对等证书的签发人/主体/ `validFrom` 编号 : `validTo` / 议定书—— 在同一文书中记录和发射 `journey/network_info` 浏览器行程使用的事件 .

## 文档

-   [导言](https://www.elastic.co/guide/en/observability/current/monitor-uptime-synthetics.html#monitoring-synthetics)
-   [CLI 选项](https://www.elastic.co/guide/en/observability/current/synthetics-command-reference.html#elastic-synthetics-command)
-   [语法](https://www.elastic.co/guide/en/observability/current/synthetics-create-test.html#synthetics-syntax)
-   [创建旅程](https://www.elastic.co/guide/en/observability/current/synthetics-create-test.html#synthetics-create-journey)
-   [创建步骤](https://www.elastic.co/guide/en/observability/current/synthetics-create-test.html#synthetics-create-step)
-   [通过 CLI 运行](https://www.elastic.co/guide/en/observability/current/synthetics-create-test.html#synthetics-test-suite)
-   [通过心跳运行](https://www.elastic.co/guide/en/observability/current/synthetics-create-test.html#synthetics-inline-journey)

完整的文档可以保存 [弹性.co](https://www.elastic.co/guide/en/observability/current/synthetic-monitoring.html)

有问题吗? 想留下反馈吗? 访问 [合成讨论 论坛](https://discuss.elastic.co/tags/c/observability/uptime/75/synthetics)。 。 。 .

## 捐款

欢迎各方提供捐款,但我们建议大家先看一看我们的捐款指南.

  
由Elastic和我们的社区制造.

## 常见问题

### @elastic/synthetics 是什么？

弹性合成监测剂

### 如何安装 @elastic/synthetics？

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

### @elastic/synthetics 支持 TypeScript 吗？

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

### @elastic/synthetics 支持 ESM 还是 CommonJS？

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

### @elastic/synthetics 需要什么版本的 Node\.js？

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

### @elastic/synthetics 可以商用吗？

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

### @elastic/synthetics 的下载量有多少？

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

### @elastic/synthetics 还在维护吗？

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