Skip to content

feat: add partial web platform support - #1

Merged
AmisKwok merged 6 commits into
mainfrom
chore/release-1.0.1
Sep 13, 2026
Merged

AmisKwok merged 6 commits into
mainfrom
chore/release-1.0.1

Conversation

@AmisKwok

@AmisKwok AmisKwok commented Sep 13, 2026 •

Copy link
Copy Markdown
Member

Summary / 摘要

Add partial Flutter Web support and ship it as 1.0.1, together with a CORS fix for the speed test, broader Windows VPN detection, and recovery of the app icons an earlier line-ending normalisation corrupted.
为插件新增 Flutter Web 部分支持并发布 1.0.1,同时修复 Web 端测速的 CORS 预检问题、扩展 Windows VPN 判定,并恢复此前换行归一化损坏的应用图标。

Changes / 变更

  • Web platform (partial) — split the dart:io-dependent services into io/web variants behind conditional imports, add the web platform entry plus ZeroNetworkKitWeb, and add an example/web/ entry point / 将依赖 dart:io 的服务拆分为 io/web 两份实现并以条件导入隔离,新增 web 平台声明与 ZeroNetworkKitWeb,并补充 example/web/ 入口
  • Connectivity uses connectivity_plus, ping degrades to an HTTPS round trip, DNS uses DNS-over-HTTPS; the speed test, quality score and benchmarks keep working unchanged / 连通性走 connectivity_plus,Ping 退化为 HTTPS 往返耗时,DNS 改用 DNS-over-HTTPS;测速、质量评分与基准测试行为不变
  • Graceful degradation: native details report null, port checks return an "unavailable" result, and NetworkCapabilities.current() exposes the supported set / 优雅降级:原生详情返回 null,端口检测返回"不可用"结果,NetworkCapabilities.current() 暴露当前支持的能力集合
  • Fix — drop the Cache-Control request header: it is not CORS-safelisted, so it forced an OPTIONS preflight that endpoints reject, surfacing as Failed to fetch on the web / 移除 Cache-Control 请求头:它不属于 CORS 安全头,会触发被端点拒绝的 OPTIONS 预检,在 Web 上表现为 Failed to fetch
  • Fix — Windows now also recognises VPN adapters by driver name (TAP-Windows / Wintun / WireGuard / OpenVPN); IF_TYPE_PPP is deliberately excluded because PPPoE broadband shares that interface type / Windows 额外按驱动名识别 VPN 网卡(TAP-Windows / Wintun / WireGuard / OpenVPN);有意排除 IF_TYPE_PPP,因为 PPPoE 宽带共用该接口类型
  • Fix — restore the 31 app icons (Android / iOS / macOS / Windows) that an earlier normalisation rewrote as UTF-8, replacing non-ASCII bytes with U+FFFD / 恢复 31 个被此前归一化按 UTF-8 重写(非 ASCII 字节被替换为 U+FFFD)的应用图标
  • Docs — document web support in both READMEs and on the docs site, and add the bilingual 1.0.1 changelog / 在两份 README 与文档站中说明 Web 支持,并补充双语的 1.0.1 变更日志

Context / 背景

The plugin previously could not compile for the web at all because its services imported dart:io, so every consumer targeting Flutter Web was blocked. Browsers also forbid raw TCP/UDP sockets and expose no VPN API, so web support is intentionally partial and documented as such instead of silently returning wrong values.
此前插件因服务层导入 dart:io 而完全无法编译到 Web,所有面向 Flutter Web 的使用方都被阻塞。浏览器同时禁止原生 TCP/UDP 套接字且不暴露 VPN 接口,因此 Web 支持有意设计为部分支持并明确文档化,而不是静默返回错误结果。

Checklist / 检查项

  • Title follows Conventional Commits / 标题符合约定式提交
  • CI checks pass after merge / 合入后 CI 通过

Test plan

  • flutter analyze reports no issues and flutter test passes (49 tests) / flutter analyze 无问题,flutter test 通过(49 个用例)
  • flutter build web succeeds in example/ / 在 example/ 下 flutter build web 构建成功
  • Run the example on web: connectivity / DNS (DoH) / speed test work, port check reports "unavailable", isVpn stays false even with a VPN or proxy active / 在 Web 上运行 example:连通性、DNS(DoH)、测速可用,端口检测返回"不可用",即使开启 VPN 或代理 isVpn 仍为 false
  • Run the example on Windows/Android to confirm no regression in VPN detection and app icons / 在 Windows/Android 上运行 example,确认 VPN 判定与图标无回归

🤖 Generated with Zero Buddy

Split the services that depend on dart:io into io/web variants behind conditional imports so the plugin compiles for Flutter Web. Connectivity uses connectivity_plus, ping degrades to an HTTPS round trip, DNS uses DNS-over-HTTPS, and the speed test, quality score and benchmarks are unchanged. Capabilities the browser sandbox forbids degrade to null or an unavailable result instead of throwing.

将依赖 dart:io 的服务拆分为 io/web 两份实现并以条件导入隔离,使插件可编译到 Flutter Web;浏览器沙箱禁止的能力优雅降级为 null 或不可用结果而非抛异常。
Cache-Control is not a CORS-safelisted header, so sending it forces an OPTIONS preflight that speed-test endpoints reject, surfacing as Failed to fetch on the web. The endpoints already send Cache-Control: no-store themselves.

Cache-Control 不属于 CORS 安全头,发送它会触发被测速端点拒绝的 OPTIONS 预检,在 Web 上表现为 Failed to fetch;端点自身已下发 no-store。
Only IF_TYPE_TUNNEL was treated as a VPN, which missed TAP-Windows, Wintun, WireGuard and OpenVPN adapters. IF_TYPE_PPP is deliberately excluded because PPPoE broadband reports the same interface type and would be misreported.

此前仅将 IF_TYPE_TUNNEL 视为 VPN,漏掉 TAP-Windows、Wintun、WireGuard、OpenVPN 等网卡;有意排除 IF_TYPE_PPP,因为 PPPoE 宽带上报同一接口类型,会被误报。
The earlier line-ending normalisation rewrote binary assets as UTF-8, replacing non-ASCII bytes with U+FFFD and breaking the Android, iOS, macOS and Windows app icons. Restore them from c2638f9.

此前换行归一化把二进制资源按 UTF-8 重写,非 ASCII 字节被替换为 U+FFFD,导致 Android、iOS、macOS、Windows 应用图标损坏。从 c2638f9 恢复。
Sync the iOS and macOS podspecs and the README dependency constraint to 1.0.1, document the partial web support in both READMEs, and add the bilingual 1.0.1 changelog entry.

同步 iOS 与 macOS podspec 及 README 依赖约束至 1.0.1,在两份 README 中说明 Web 部分支持,并补充双语的 1.0.1 变更日志。
Platform-Support.md no longer claims Web is unsupported: the intro, capability matrix and NetworkCapabilities rules now cover the web, and a dedicated Web support section lists which capabilities degrade and notes that browsers expose no VPN API. FAQ.md is updated to match.

Platform-Support.md 不再声称不支持 Web:开头、能力矩阵与 NetworkCapabilities 规则均已覆盖 Web,并新增 Web 支持章节列出各能力的降级行为,同时说明浏览器不暴露 VPN 接口;FAQ.md 同步更新。
@AmisKwok
AmisKwok merged commit 57f5831 into main Sep 13, 2026
13 checks passed
@AmisKwok
AmisKwok deleted the chore/release-1.0.1 branch September 13, 2026 23:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant