开始使用

安装

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

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

然后使用以下提示：

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

如果您更喜欢手动设置，请按照以下命令安装插件并遵循以下平台特定的说明：

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

导入

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

运行完整诊断报告

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);

具体的标志取决于平台。 Android 可以报告验证的互联网和捕获门户状态。 iOS 报告路径状态、接口类型、昂贵路径和受限路径。 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 fallback

浏览器无法打开原始 TCP sockets，URL 检查可能受 CORS 限制。请使用 iOS 或 Android 构建来获得真实支持诊断。