快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

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

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-network-diagnostics
bunx cap sync

导入

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

快速入门

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

const result = await NetworkDiagnostics.getNetworkStatus();
console.log(result);

示例：testUrl

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

const result = await NetworkDiagnostics.testUrl({ url: 'https://example.com' });
console.log(result);

示例：testPort

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

const result = await NetworkDiagnostics.testPort({
  host: 'example.com',
  port: 8080,
});
console.log(result);

常见坑点

• 原生同步：运行 bunx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

运行完整诊断报告

runDiagnostics 是在受限网络环境下为用户收集支持报告的最快方式。

const report = await NetworkDiagnostics.runDiagnostics({
  urls: [{ url: 'https://api.example.com/health', method: 'HEAD' }],
  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.status.connectionType);
console.log(report.issues);

检查当前网络状态

const status = await NetworkDiagnostics.getNetworkStatus();

console.log(status.connected);
console.log(status.connectionType);
console.log(status.internetReachable);
console.log(status.captivePortal);

The exact flags depend on the platform. Android can report validated internet and captive portal state. iOS reports path status, interface type, expensive paths, and constrained paths through Network.framework.

测试 API 可达性

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

if (!result.reachable) {
  console.warn(result.errorCode, result.errorMessage);
}

请使用后端真实的健康检查端点。仅基于浏览器的检查可能会被 WebView、CORS、代理或强制门户行为掩盖，而此插件使用原生网络。

测试 TCP 端口

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

console.log(port.open, port.durationMs);

当 Wi-Fi 接入点阻止非标准端口、MQTT、自定义网关或私有后端，但仍允许正常浏览时，这非常有用。

测试 WebSocket 连接

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

console.log(socket.open, socket.statusCode);

当代理或强制门户允许 HTTPS 页面但拦截 WebSocket 升级请求时，请使用此方法。

测量下载速度

const speed = await NetworkDiagnostics.testDownloadSpeed({
  url: 'https://speed.example.com/5mb.bin',
  maxBytes: 5 * 1024 * 1024,
  timeoutMs: 30000,
});

console.log(speed.mbps);

使用你自己的静态文件端点，以便结果能真实反映你的应用所需的网络路径。

估算丢包率

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

console.log(loss.lossPercent);

原始 ICMP ping 在 App Store 和 Play Store 应用中无法直接使用。此方法通过重复进行 TCP 或 HTTP 探测来测量应用层丢包率。

Web 回退方案

Web 实现仅供开发使用。浏览器无法打开原始 TCP socket，且 URL 检查可能受 CORS 限制。如需进行真正的支持诊断，请使用 iOS 或 Android 构建。