# @capgo/capacitor-network-diagnostics 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/

版本：8\.0\.15
npm 元数据更新时间：2026-10-15T05:56:57.427Z
中文译文更新时间：2026-11-09T04:12:52.470Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-network-diagnostics
原文对照：https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/?lang=original
项目主页：https://capgo.app/docs/plugins/network-diagnostics/
源码仓库：https://github.com/Cap-go/capacitor-network-diagnostics

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

- 包体积（解压后）：280 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-05-29T16:19:37.252Z
- 最新版本发布：2026-10-15T05:56:57.103Z
- 近 30 天下载量：39707（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

本地网络诊断的电容插件.

## 安装

```sh
npm install @capgo/capacitor-network-diagnostics
```

也可以使用：`pnpm add @capgo/capacitor-network-diagnostics`、`yarn add @capgo/capacitor-network-diagnostics`、`bun add @capgo/capacitor-network-diagnostics`

## README

# @capgo/电容-网络-诊断

找出为什么您的 Capacitor app 无法到达您的后端: 测试连接类型, HTTP 可达性, TCP 端口, WebSockets, 下载速度以及设备本身的包丢失 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-network-diagnostics)](https://capgo.app/?ref=plugin_network_diagnostics)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_network_diagnostics)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_network_diagnostics) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-network-diagnostics` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-network-diagrostics到我的Capacitor应用上,并把它接上。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_network_diagnostics) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_network_diagnostics)

![@capgo/capacitor-network-diagnostics for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-network-diagnostics/main/assets/github-social-preview.png)

## 主要特点

-   **网络状态**数字 : `getNetworkStatus()` 返回本地连接类型和网络旗.
-   **可达到性**数字 : `testUrl()` 用于 HTTP 或 HTTPS 和 `testPort()` 一个TCP主机和端口.
-   **网络软件**数字 : `testWebSocket()` 检查握手完成.
-   **业绩**数字 : `testDownloadSpeed()` 财务报告和审定财务报表 `testPacketLoss()`。 。 。 .
-   **一份报告**数字 : `runDiagnostics()` 运行数个检查并返回压缩摘要.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. Web 运行浏览器能力检查 。 TCP端口测试需要本土代码.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-network-diagnostics` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-network-diagnostics
npx cap sync
```

## 测试什么

-   目前本地连接类型:WiFi,蜂窝,ethenet,VPN,无,或未知.
-   OS网络旗:在Android上验证了互联网,在Android上封存了门户,如果有的话费用昂贵或受限制的路径.
-   原生HTTP/HTTPS URL可达性,具有状态代码和耐用性.
-   原生TCP主机:端口连接.
-   本地 WebSocket 握手方式 `ws://` 财务报告和审定财务报表 `wss://`。 。 。 .
-   根据自己的测试文件端点下载吞吐量 .
-   使用重复的 TCP 连接或 HTTP 请求来丢失包.

App Store和Play Store应用软件的Raw ICMP ping并不一致. `testPacketLoss` 因此,用TCP或HTTP探测器测量应用级损失.

## 使用量

```typescript
import { NetworkDiagnostics } from '@capgo/capacitor-network-diagnostics';

const status = await NetworkDiagnostics.getNetworkStatus();

const api = await NetworkDiagnostics.testUrl({
  url: 'https://api.example.com/health',
  method: 'HEAD',
  timeoutMs: 5000,
});

const port = await NetworkDiagnostics.testPort({
  host: 'api.example.com',
  port: 443,
  timeoutMs: 3000,
});

const ws = await NetworkDiagnostics.testWebSocket({
  url: 'wss://ws.example.com/socket',
  timeoutMs: 5000,
});

const packetLoss = await NetworkDiagnostics.testPacketLoss({
  mode: 'tcp',
  host: 'api.example.com',
  port: 443,
  count: 10,
});

console.log({ status, api, port, ws, packetLoss });
```

## 合并诊断运行

```typescript
const report = await NetworkDiagnostics.runDiagnostics({
  urls: [{ url: 'https://api.example.com/health' }],
  ports: [{ host: 'api.example.com', port: 443 }],
  websockets: [{ url: 'wss://ws.example.com/socket' }],
  download: {
    url: 'https://speed.example.com/5mb.bin',
    maxBytes: 5 * 1024 * 1024,
  },
  packetLoss: {
    mode: 'tcp',
    host: 'api.example.com',
    port: 443,
    count: 10,
  },
});

console.log(report.issues);
```

## 平台说明

-   iOS:不需要额外权限. 连接类型来自 `Network.framework`。 。 。 .
-   Android: 插件声明 `android.permission.INTERNET` 财务报告和审定财务报表 `android.permission.ACCESS_NETWORK_STATE`。 。 。 .
-   Web:作为开发后退提供. 浏览器无法打开原始的 TCP 套接字, 且 URL 检查受 CORS 限制 .

## API 密码

-   [`getNetworkStatus()`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-getnetworkstatus)
-   [`testUrl(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-testurl)
-   [`testPort(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-testport)
-   [`testWebSocket(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-testwebsocket)
-   [`testDownloadSpeed(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-testdownloadspeed)
-   [`testPacketLoss(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-testpacketloss)
-   [`runDiagnostics(...)`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-rundiagnostics)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-type-aliases)

原生网络诊断API.

### 获取网络状态

```typescript
getNetworkStatus() => Promise<NetworkStatusResult>
```

读取当前本地连接类型和平台网络旗.

**回返情况:** `Promise<[NetworkStatusResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-networkstatusresult)>`

* * *

### testUrl (...)

```typescript
testUrl(options: UrlTestOptions) => Promise<UrlTestResult>
```

测试 HTTP 或 HTTPS URL 是否能够从本地网络中达到 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[UrlTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-urltestoptions)` |

**回返情况:** `Promise<[UrlTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-urltestresult)>`

* * *

### 测试端口(...)

```typescript
testPort(options: PortTestOptions) => Promise<PortTestResult>
```

测试 TCP 主机: 端口能否从本地网络打开 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PortTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-porttestoptions)` |

**回返情况:** `Promise<[PortTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-porttestresult)>`

* * *

### 测试WebSocket(...)

```typescript
testWebSocket(options: WebSocketTestOptions) => Promise<WebSocketTestResult>
```

测试一个 WebSocket URL能否完成本土握手.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[WebSocketTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-websockettestoptions)` |

**回返情况:** `Promise<[WebSocketTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-websockettestresult)>`

* * *

### 已下载Speed(...)

```typescript
testDownloadSpeed(options: DownloadSpeedTestOptions) => Promise<DownloadSpeedTestResult>
```

测量本地 HTTP 请求的下载吞吐量 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DownloadSpeedTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-downloadspeedtestoptions)` |

**回返情况:** `Promise<[DownloadSpeedTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-downloadspeedtestresult)>`

* * *

### 测试包Loss(...)

```typescript
testPacketLoss(options: PacketLossTestOptions) => Promise<PacketLossTestResult>
```

使用重复的 TCP 或 HTTP 探测器估计应用级包丢失 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PacketLossTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlosstestoptions)` |

**回返情况:** `Promise<[PacketLossTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlosstestresult)>`

* * *

### 运行分析(...)

```typescript
runDiagnostics(options?: RunDiagnosticsOptions | undefined) => Promise<RunDiagnosticsResult>
```

运行多个诊断并返回一个紧凑的问题清单.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RunDiagnosticsOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-rundiagnosticsoptions)` |

**回返情况:** `Promise<[RunDiagnosticsResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-rundiagnosticsresult)>`

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<PluginVersionResult>
```

返回平台执行版本标记 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-pluginversionresult)>`

* * *

### 接口

#### 网络状态

目前本地网络状态.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`connected`** | `boolean` | 当平台报告活跃的网络路径时为真. |
| **`connectionType`** | `[ConnectionType](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-connectiontype)` | 最佳活动运输类型. |
| **`internetReachable`** | `boolean` | 当操作系统将网络标记为具有互联网能力或验证能力时,这是真的. |
| **`expensive`** | `boolean` | 真实的或昂贵的网络路径. |
| **`constrained`** | `boolean` | 当OS报告一个低数据或受限的网络路径时是真实的. |
| **`captivePortal`** | `boolean` | 当Android报告被俘的传送门能力时是真实的. |
| **`details`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-record)<string, string | number | boolean>` | 本地平台细节对调试有用. |

#### 乌尔测试结果

原生HTTP URL可达性结果.

| Prop | 类型 |
| --- | --- |
| **`url`** | `string` |
| **`method`** | `[UrlTestMethod](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-urltestmethod)` |
| **`ok`** | `boolean` |
| **`reachable`** | `boolean` |
| **`durationMs`** | `number` |
| **`statusCode`** | `number` |
| **`finalUrl`** | `string` |
| **`errorCode`** | `string` |
| **`errorMessage`** | `string` |

#### 乌尔测试选项

本地 HTTP URL 可达性检查的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`url`** | `string` | HTTP或HTTPS URL要测试. |
| **`method`** | `[UrlTestMethod](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-urltestmethod)` | HTTP 方法 。 默认为 `HEAD`。 。 。 . |
| **`timeoutMs`** | `number` | 请求超时, 以毫秒计 。 默认为 `10000`。 。 。 . |
| **`followRedirects`** | `boolean` | 跟踪方向 默认为 `true`。 。 。 . |

#### 港口测试结果

本地 TCP 端口检查结果 .

| Prop | 类型 |
| --- | --- |
| **`host`** | `string` |
| **`port`** | `number` |
| **`open`** | `boolean` |
| **`durationMs`** | `number` |
| **`errorCode`** | `string` |
| **`errorMessage`** | `string` |

#### 端口测试选项

本地 TCP 端口检查选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`host`** | `string` | 主机名或IP地址 . |
| **`port`** | `number` | TCP端口开通. |
| **`timeoutMs`** | `number` | 以毫秒计算超时 。 默认为 `5000`。 。 。 . |

#### WebSocket 测试结果

本地WebSocket握手结果.

| Prop | 类型 |
| --- | --- |
| **`url`** | `string` |
| **`open`** | `boolean` |
| **`durationMs`** | `number` |
| **`protocol`** | `string` |
| **`statusCode`** | `number` |
| **`errorCode`** | `string` |
| **`errorMessage`** | `string` |

#### WebSocket 测试选项

本地 WebSocket 握手检查选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`url`** | `string` | `ws://` 或者说 `wss://` URL要测试. |
| **`timeoutMs`** | `number` | 握手暂停数毫秒。 默认为 `10000`。 。 。 . |

#### 下载测试结果

原地下载速度测量结果.

| Prop | 类型 |
| --- | --- |
| **`url`** | `string` |
| **`ok`** | `boolean` |
| **`durationMs`** | `number` |
| **`bytesDownloaded`** | `number` |
| **`bytesPerSecond`** | `number` |
| **`mbps`** | `number` |
| **`statusCode`** | `number` |
| **`errorCode`** | `string` |
| **`errorMessage`** | `string` |

#### 下载测试选项

本地下载速度测量选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`url`** | `string` | HTTP或HTTPS URL返回一个可下载的正文. |
| **`maxBytes`** | `number` | 停止前要读取的最大字节 。 默认为 `5242880` (5个米B. |
| **`timeoutMs`** | `number` | 请求超时, 以毫秒计 。 默认为 `30000`。 。 。 . |

#### 包装丢失测试结果

应用程序级包丢失结果 .

| Prop | 类型 |
| --- | --- |
| **`mode`** | `[PacketLossMode](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlossmode)` |
| **`target`** | `string` |
| **`sent`** | `number` |
| **`received`** | `number` |
| **`lost`** | `number` |
| **`lossPercent`** | `number` |
| **`averageLatencyMs`** | `number` |
| **`minLatencyMs`** | `number` |
| **`maxLatencyMs`** | `number` |
| **`errorCode`** | `string` |
| **`errorMessage`** | `string` |

#### 包丢失测试选项

包损失计量的选项 .

原生应用程序不能依赖原始的 ICMP ping 和 iOS 和 Android,所以这个 用重复的 TCP 连接或 HTTP 测量应用级别损失的方法 请求.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`mode`** | `[PacketLossMode](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlossmode)` | 探测模式。 默认为 `tcp` 提供主机/端口时,否则 `http`。 。 。 . |
| **`host`** | `string` | TCP探测器的主机名或IP地址. |
| **`port`** | `number` | TCP端口用于TCP探测. |
| **`url`** | `string` | HTTP或HTTP URL用于HTTP探测器. |
| **`count`** | `number` | 要发送的探测器数量 。 默认为 `10`。 。 。 . |
| **`timeoutMs`** | `number` | 用毫秒计时 默认为 `3000`。 。 。 . |
| **`intervalMs`** | `number` | 探测器之间的延迟数以毫秒计。 默认为 `250`。 。 。 . |

#### 运行诊断结果

本地网络综合诊断结果.

| Prop | 类型 |
| --- | --- |
| **`status`** | `[NetworkStatusResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-networkstatusresult)` |
| **`urls`** | `UrlTestResult[]` |
| **`ports`** | `PortTestResult[]` |
| **`websockets`** | `WebSocketTestResult[]` |
| **`issues`** | `string[]` |
| **`download`** | `[DownloadSpeedTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-downloadspeedtestresult)` |
| **`packetLoss`** | `[PacketLossTestResult](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlosstestresult)` |

#### 运行分析选项

综合本土网络诊断运行的选项.

| Prop | 类型 |
| --- | --- |
| **`urls`** | `UrlTestOptions[]` |
| **`ports`** | `PortTestOptions[]` |
| **`websockets`** | `WebSocketTestOptions[]` |
| **`download`** | `[DownloadSpeedTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-downloadspeedtestoptions)` |
| **`packetLoss`** | `[PacketLossTestOptions](https://npmcn.com/package/%40capgo/capacitor-network-diagnostics/#readme-packetlosstestoptions)` |

#### 插件变压器

插件版本有效载荷 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`version`** | `string` | 版本标识符由平台执行返回. |

### 类型异名

#### 连接类型

`'none' | 'wifi' | 'cellular' | 'ethernet' | 'vpn' | 'other' | 'unknown'`

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

#### 乌尔测试方法

`'HEAD' | 'GET'`

#### 包装丢失模式

`'tcp' | 'http'`

## 常见问题

### @capgo/capacitor-network-diagnostics 是什么？

本地网络诊断的电容插件\.

### 如何安装 @capgo/capacitor-network-diagnostics？

在项目目录运行 npm install @capgo/capacitor-network-diagnostics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-network-diagnostics 支持 TypeScript 吗？

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

### @capgo/capacitor-network-diagnostics 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-network-diagnostics 可以商用吗？

@capgo/capacitor-network-diagnostics 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-network-diagnostics 的下载量有多少？

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

### @capgo/capacitor-network-diagnostics 还在维护吗？

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