快速开始

前置要求

• Flutter SDK
• Go 1.21+ (用于编译核心库)
• Android Studio / Xcode

安装

在您的 pubspec.yaml 中添加 dynamic_domain 依赖：

dependencies:
  dynamic_domain:
    path: ../dynamic_domain # 或者使用 git url

基础用法

在 main.dart 中初始化 SDK：

import 'package:dynamic_domain/dynamic_domain.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 1. 创建 SDK 实例
  final dynamicDomain = DynamicDomain();
  
  // 2. 初始化 (需要 App ID)
  // 注意：请联系客服 (@zhuanmitools) 获取您的专属 App ID
  final String appId = "your_app_id";
  await dynamicDomain.init(appId);
  
  // 3. 获取远程配置
  String config = await dynamicDomain.fetchRemoteConfig(appId);
  
  // 4. 启动隧道
  // 返回本地代理地址 (例如 "127.0.0.1:10809")
  String proxyUrl = await dynamicDomain.startTunnel(config);
  
  print("隧道已启动，代理地址: $proxyUrl");
  
  runApp(MyApp());
}

初始化成功并启动隧道后，您可以使用返回的 proxyUrl 来配置您的网络请求或 WebView。

最佳实践与注意事项

为了确保 SDK 的稳定运行和最佳性能，请遵循以下开发建议：

1. 避免并发冲突

SDK 的 init、startTunnel 和 stopTunnel 是状态敏感的操作。

• 不要并发调用：请确保同一时间只有一个初始化或启动操作在进行。SDK 内部已增加保护锁，如果检测到冲突会抛出 busy 异常。
• 顺序执行：始终遵循 init -> fetchRemoteConfig -> startTunnel 的顺序。

2. 异常处理

网络环境极其复杂，建议对启动流程进行完整的错误捕获：

try {
  await dynamicDomain.startTunnel(config);
} catch (e) {
  // 可能是端口被占用、配置解密失败或内核启动失败
  print("隧道启动失败: $e");
  // 可以在此处引导用户检查网络或切换 App ID
}

3. 资源管理

• 及时停止：如果 App 退出或不再需要代理，请调用 stopTunnel() 释放本地端口和原生资源。
• 保活建议：在 Android 上，SDK 已内置前台服务。如果您需要极高稳定性的长连接（如 IM），请确保在 Android Manifest 中正确配置了权限。

进阶集成

如果您正在使用第三方 SDK（如 OpenIM、Firebase 或其他原生 C++/Go 核心的库），建议阅读：

• OpenIM 集成指南 - 了解如何为长连接 IM 框架配置 SOCKS5 代理。
• WebView 代理集成 - 让您的 H5 页面也具备抗封锁能力。