更新记录

1.0.3（2026-09-09）

• 更新readme

1.0.2（2026-09-09）

• 更新插件名称

1.0.1（2026-09-09）

• 完善readme文档

平台兼容性

uni-app(4.75)

uni-app x(4.75)

其他

jagger-wifi-tcp

史上最全wifi操控API + TCP SOCKET的物联网数据传输；

Wi-Fi 与 TCP Socket 能力可以单独使用，也可以结合使用：单独使用 Wi-Fi 能力管理连接、读取当前网络信息；单独使用 TCP Socket 能力，通过系统路由连接服务端并收发数据，无需由插件发起 Wi-Fi 连接。

结合使用时，设置 networkMode: 'wifi' 可让 TCP 通过 Wi-Fi 与设备通信。Android 将 Socket 绑定到插件管理的 Wi-Fi Network，域名解析也通过该 Network；iOS 将连接限定在 Wi-Fi 接口。这样可以减少系统默认路由选择及蜂窝网络对设备通信路径的影响，让网络通道更稳定。

快速上手（重点关注）

1. 点击右上角“试用”按钮，并导入插件到宿主项目。
2. iOS打包前，需要配置描述文件，对应2个能力见【iOS 打包前配置】（安卓可跳过）
3. 使用项目证书(Android)/描述文件+证书（iOS）打包自定义基座
4. 调用代码：

import * as connection from '@/uni_modules/jagger-wifi-tcp'

const listenerId = connection.onSocketMessage(event => {
    console.log(event.socketId, event.data) // 0–255 字节数组，TCP 不保证消息边界
})

connection.connectWifi({
    SSID: 'Device-AP',
    password: 'your-device-password',
    timeout: 30000,
    success: wifiResult => {
        if (wifiResult.verified === false) {
            // 本示例采用保守策略：先让用户确认目标网络，再重新读取或进行设备身份验证。
            console.warn('Wi-Fi 配置已接受，但尚未确认目标 SSID', wifiResult.errMsg)
            return
        }
        connection.connectSocket({
            host: '192.168.4.1',
            port: 9000,
            networkMode: 'wifi',
            connectTimeout: 15000,
            success: () => connection.writeSocket({ data: [0xAA, 0x01, 0xFF], fail: console.error }),
            fail: console.error
        })
    },
    fail: console.error
})

// 使用完后：
// connection.offSocketMessage(listenerId)
// connection.disconnectSocket({})
// connection.stopWifi({})

安装

把本目录复制到宿主项目 uni_modules。HBuilderX 4.75+，手机端 Vue 3 示例已提供。uni-app x 保留同一公共接口，宿主运行模式的最低系统要求可能更高，发布前需在实际宿主工程编译验收。

iOS 打包前配置

在 Apple Developer 的 Identifiers 页面选择与宿主 App Bundle ID 一致的 App ID，开启并保存以下两项能力：

• 开启 Access Wi-Fi Information：用于读取当前连接的 Wi-Fi 名称和 BSSID，对应 com.apple.developer.networking.wifi-info。
• 开启 Hotspot：对应 Xcode 中的 Hotspot Configuration，用于在 App 内按 SSID、密码连接 Wi-Fi，对应 com.apple.developer.networking.HotspotConfiguration。只开启 Access Wi-Fi Information 不能满足本插件的连接功能。

保存后，重新生成并下载该 App ID 对应的描述文件（.mobileprovision），替换 HBuilderX 打包配置中的旧描述文件，再制作 iOS 自定义基座或正式打包。

插件的内部已声明这两项能力，但不能代替开发者签名描述文件的配置，且权限用途描述由宿主统一在manifest.json中提供，插件不内置描述文案。

宿主权限配置

• 插件内部已包含 Android 权限和 iOS 能力声明，接入时无需再在宿主 manifest.json 中额外添加同样的声明。
• iOS使用本插件完整 Wi-Fi/TCP 功能时，必须在宿主 manifest.json 中配置下列两项描述。Apple 开发者后台启用能力及更新描述文件需接入方完成。

Android 权限清单

以下权限已声明在插件内。

单独使用系统路由 TCP 不会因为调用 connectSocket 而申请 Wi-Fi 定位权限；Android 新版本的本地网络权限仍按上述条件处理。扫描需要系统 Wi-Fi 和定位服务处于开启状态，权限授权不等于开关已开启。

iOS 能力与权限用途描述清单

getConnectedWifi 先尝试读取，必要时才申请定位；TCP 通信不会为读取 SSID 而主动申请定位。本插件未使用 Bonjour 服务发现，因此不需要为本插件添加 NSBonjourServices。

以下是使用完整 Wi-Fi/TCP 功能所需的 iOS 用途描述配置。该片段适用于当前 uni-app（非 uni-app x） 宿主：将文案改为实际业务用途后，合并到现有 manifest.json，不要覆盖 AppID、证书及其他配置。当前 demo 已包含这两项描述。uni-app x 的配置节点需按其对应版本文档填写。

{
  "app-plus": {
    "distribute": {
      "ios": {
        "deploymentTarget": "12.0",
        "privacyDescription": {
          "NSLocalNetworkUsageDescription": "用于与您选择的局域网设备建立 TCP 连接并收发数据。",
          "NSLocationWhenInUseUsageDescription": "用于在您读取当前 Wi-Fi 信息时获取网络名称。"
        }
      }
    }
  }
}

Android 10 的配网/扫描需要定位授权；扫描还需开启系统 Wi-Fi 和定位服务。拒绝授权时插件返回失败，由页面提示用户检查系统设置。 声明、原生代码或签名配置变化后须重新制作自定义基座；仅更新页面不能使这些变化生效。

调用示例：由 App 连接 Wi-Fi 后连接 TCP

import * as connection from '@/uni_modules/jagger-wifi-tcp'

const listenerId = connection.onSocketMessage(event => {
  console.log(event.socketId, event.data) // 0–255 字节数组，TCP 不保证消息边界
})

connection.connectWifi({
  SSID: 'Device-AP',
  password: 'your-device-password',
  timeout: 30000,
  success: wifiResult => {
    if (wifiResult.verified === false) {
      // 本示例采用保守策略：先让用户确认目标网络，再重新读取或进行设备身份验证。
      console.warn('Wi-Fi 配置已接受，但尚未确认目标 SSID', wifiResult.errMsg)
      return
    }
    connection.connectSocket({
      host: '192.168.4.1',
      port: 9000,
      networkMode: 'wifi',
      connectTimeout: 15000,
      success: () => connection.writeSocket({ data: [0xAA, 0x01, 0xFF], fail: console.error }),
      fail: console.error
    })
  },
  fail: console.error
})

// 使用完后：
// connection.offSocketMessage(listenerId)
// connection.disconnectSocket({})
// connection.stopWifi({})

上述 IP、端口和密码均为示例，必须替换为设备实际配置。Wi-Fi 关联成功不代表 TCP 服务已经启动。

调用示例：手机已在系统设置中连接 Wi-Fi

无需再次调用 connectWifi。在 App 页面就绪后，由用户点击连接按钮调用以下函数：先启动观察，再读取当前 Wi-Fi，最后尝试绑定 Wi-Fi 建立 TCP。

import * as connection from '@/uni_modules/jagger-wifi-tcp'

function connectUsingCurrentWifi() {
  connection.startWifi({
    success: () => connection.getConnectedWifi({
      success: result => {
        console.log('当前 Wi-Fi', result.wifi)
        connection.connectSocket({
          host: '192.168.4.1', // 替换为设备地址
          port: 9000,         // 替换为设备 TCP 服务端口
          networkMode: 'wifi',
          connectTimeout: 15000,
          success: result => console.log('TCP 已连接', result.state),
          fail: error => {
            // 9001004 可能是 Wi-Fi 路由尚未就绪；提示用户确认网络后再次点击连接。
            // 不自动切换为 system，以免悄悄改变用户选择的连接路径。
            console.error('TCP 连接失败', error.errCode, error.errMsg)
          }
        })
      },
      fail: error => console.error('读取当前 Wi-Fi 失败', error.errCode, error.errMsg)
    }),
    fail: error => console.error('启动 Wi-Fi 观察失败', error.errCode, error.errMsg)
  })
}

// 绑定到页面的连接按钮；收到 TCP success 后才能调用 writeSocket。
// 页面使用收发功能时，按上一示例注册 onSocketMessage 并在退出时移除监听。

如果业务明确需要遵循系统默认路由，可以直接调用 connectSocket({ host, port, networkMode: 'system', ... })，不必调用 startWifi 或 connectWifi；此模式不保证访问 Android 插件请求的专用设备热点。

接口

所有异步操作接收 success / fail / complete，返回值格式为 { errCode, errMsg, ... }；成功或失败只回调一次，随后执行 complete。不支持的操作明确走 fail。

平台支持表

✅ 表示该平台可以调用；❌ 表示系统不支持。iOS 不提供普通 App 扫描附近 Wi-Fi 的公开 API，因此 iOS 页面应让用户手动输入已知 SSID 和密码，再调用 connectWifi，不要调用 getWifiList。

参数与行为

以下签名与 utssdk/interface.uts 一致。字段后的 ? 表示可选；这是签名说明，实际 JavaScript 调用时不写 ?。所有操作接口的 options 对象必须传入；没有业务参数且不需要回调时传 {}。操作接口同步返回 void，结果通过回调取得，不返回 Promise。监听接口使用独立的 callback / listenerId 入参，详见下方“监听”。

通用回调参数：ApiOptions

每个操作接口都接受以下三个字段；ApiCallback 的类型为 (result: ApiResult) => void。

每次请求只完成一次。业务 success / fail 抛出异常时仍执行 complete；业务回调异常会记录到控制台，不中断插件后续通知。

只接收通用回调的接口

以下各接口的完整入参均为 options: ApiOptions，只有可选的 success、fail、complete，没有其他入参。表中的成功结果均另外包含公共字段 errCode、errMsg。

connectWifi(options: ConnectWifiOptions): void

该接口会启动所需的 Wi-Fi 观察。verified: true 表示插件已确认目标连接；iOS 系统接受配置、Wi-Fi 路径可用但 SSID 不可读时，可能成功返回 verified: false，此时不返回已确认的 wifi，也不发送连接成功事件。业务必须检查 verified，不能仅凭 errCode === 0 宣称已连接目标 SSID。

disconnectWifi(options: DisconnectWifiOptions): void

Android 10+ 只能释放插件自己请求的网络；系统管理的网络返回 9001001，需用户到系统设置断开。Android 5–9 可请求系统断开当前匹配网络。iOS 只能移除本 App 添加且确认当前正在连接的 SSID 配置。配网等待期间返回 9001008。成功表示请求被接受，不保证系统已完成断开，应再次读取实际状态。

connectSocket(options: ConnectSocketOptions): void

Android 的 'wifi' 模式要求已有可绑定网络，可先调用 startWifi 等待网络就绪，或等待 connectWifi 成功；两端都拒绝在 Wi-Fi 配网等待期间新建绑定 Wi-Fi 的 TCP。'system' 模式可单独使用，不要求先调用 Wi-Fi 接口。模式在建连时确定，没有向接口传入原生 Network 句柄的参数。

writeSocket(options: WriteSocketOptions): void

只向当前已连接会话写入，不接收 socketId、编码、追加换行或写入超时参数。发送成功仅表示字节已交给本地传输栈，不代表远端业务处理成功；业务确认需要设备协议 ACK。发送队列有上限，没有独立写入超时，远端不读取时可通过 disconnectSocket 取消写入。

通用请求结果：ApiResult

success、fail、complete 都接收一个 result 对象；可选字段只在对应操作实际返回时出现。

插件同时管理一个 Wi-Fi 请求和一个 TCP 会话。新的有效 connectWifi / connectSocket 请求进入建连流程时会替换前一次同类请求，仍在等待的旧请求以 9001007 完成；参数或前置条件检查未通过时，不应假定旧会话已被替换。

监听

注册和取消监听的完整入参

所有 onX 的入参为一个必填函数 callback: EventCallback，类型为 (event: PluginEvent) => void，没有默认值。同步返回 number 类型的 listenerId。这里传函数本身，不传 { success, fail, complete } 对象。

所有 offX 的唯一入参为可选的 listenerId: number，同步返回 void。传编号只移除对应事件的这条监听；省略参数时移除该事件的所有监听。不存在的编号或其他事件的编号不会移除当前事件的其他监听。

每次注册产生独立编号；重复注册同一个函数也会形成独立监听。注册监听不会自动发起扫描或连接，也不补发历史事件。两端都可以注册和移除以上监听，但 iOS 不产生 getWifiList 事件。

不能把回调函数传给 offX。 取消监听不会关闭 Wi-Fi 或 TCP，关闭连接也不会自动移除监听；页面退出时应主动使用对应编号清理。API 名称参考 uni-wifi，未挂载或覆盖全局 uni.*。

const listenerId = connection.onSocketMessage(event => {
  console.log(event.socketId, event.data)
})

connection.offSocketMessage(listenerId) // 只移除上面这一条
// connection.offSocketMessage()       // 移除全部 TCP 收包监听，谨慎用于多个页面共享的插件

监听回调入参：PluginEvent

每次回调接收一个 event 对象。其 event 字段为必有的 string 类型；其他字段在公共类型中均为可选，实际内容按下面的事件区分。wifi / state 的内部字段见后面的类型表。

Wi-Fi 信息字段：WifiInfo

系统未提供的可选字段保持缺省，不能当作 false 或 0；SSID 不可读不等于未连接。

TCP 状态字段：SocketState

以下字段在 SocketState 中均为必填。

建连阶段失败或超时只调用本次 connectSocket 的 fail，不会再重复发出 SocketError，但可以同时产生断开状态事件。iOS 对可恢复的 waiting 按错误内容去重；明确连接被拒绝会立即结束，暂时无路由、地址不可用或等待本地网络授权则保留连接，直到成功、系统报告失败、用户取消或达到连接超时。参数或权限检查失败不保证产生会话事件。

权限与错误

Android 权限声明随插件合并。Android 13+ 的附近 Wi-Fi 权限不能替代扫描所需的定位权限。Android 17 且 targetSdk >= 37 才请求新本地网络权限；需要宿主打包工具链支持相应目标 SDK。

iOS 能力、描述文件及用途文案配置见上方“iOS 打包前配置”和“宿主权限配置”。getConnectedWifi 先尝试系统读取，必要时请求定位；不是每次 TCP 都申请定位。没有 Bonjour 业务，因此未声明 NSBonjourServices。

错误码为本插件自定义码，原生错误信息保留在 errMsg 供排查。

常见问题排查

• 如有疑问，请联系微信：jagger-yu 💌
• 反馈问题时提供：手机型号、系统版本、HBuilderX 版本、使用的基座是否重新制作、具体操作、errCode/errMsg 和相关时序日志。扫描问题另附缺失 SSID 与系统列表对照；TCP 问题附目标 IP/端口及服务状态。不要提交 Wi-Fi 密码、证书私钥或完整签名凭据。

参考：uni-wifi、Android Network、Wi-Fi Network Request、Apple Wi-Fi API、Apple 本地网络隐私。