更新记录

1.0.2（2026-03-12）

示例代码添加 node服务端示例

1.0.1（2025-12-19）

修复获取端口失败问题

1.0.0（2025-12-18）

发现设备

平台兼容性

uni-app(4.83)

uni-app x(4.83)

wzq-mNDS 局域网mDNS扫描插件

📋 概述

wzq-mNDS 是一个基于 Android 平台的局域网 mDNS 设备扫描插件，提供高效的局域网设备发现功能。支持多种服务类型扫描，能够发现局域网中的智能设备、打印机、媒体服务器等 mDNS 广播服务。

✨ 功能特性

• 多服务类型支持：内置常见 mDNS 服务类型（HTTP、HTTPS、FTP、SSH、打印机等）
• 并发扫描优化：使用线程池并发查询，提高扫描效率
• 智能网络检测：自动识别 WiFi 网络状态和本机 IP 地址
• 完善的错误处理：提供详细的错误信息和网络诊断报告
• 适配现代 Android API：基于 Android 6.0+ 的现代网络 API 实现
• 无第三方依赖：纯 Android 系统 API 实现，无需额外依赖

📱 兼容性

• Android 版本：6.0 (API 23) 及以上
• 网络要求：WiFi 网络连接，支持多播通信
• 权限要求：需要网络访问权限

🚀 快速开始

1. 检查 mDNS 功能可用性

import { isMDNSAvailable } from '@/uni_modules/wzq-mNDS';

// 检查设备是否支持 mDNS 功能
const available = isMDNSAvailable();
console.log('mDNS 功能可用:', available);

2. 扫描局域网设备

import { scanServices } from '@/uni_modules/wzq-mNDS';

// 扫描指定服务类型
scanServices({
  serviceTypes: ['_http._tcp.local.'], // 可选，默认为常见服务类型
  timeout: 5000, // 可选，扫描超时时间（毫秒）
  success: (result) => {
    console.log('扫描成功，发现设备:', result.devices);
    console.log('设备数量:', result.count);
  },
  fail: (error) => {
    console.error('扫描失败:', error);
  },
  complete: (result) => {
    console.log('扫描完成');
  }
});

3. 获取本机 IP 地址

import { getLocalIP } from '@/uni_modules/wzq-mNDS';

// 获取本机 WiFi IP 地址
const localIP = getLocalIP();
console.log('本机 IP 地址:', localIP);

4. 批量获取设备列表

import { getMDNSDeviceList } from '@/uni_modules/wzq-mNDS';

getMDNSDeviceList({
  timeout: 8000, // 可选，扫描超时时间
  success: (result) => {
    console.log('设备列表:', result.devices);
    console.log('总设备数:', result.totalDevices);
  },
  fail: (error) => {
    console.error('获取设备列表失败:', error);
  }
});

📊 API 文档

scanServices(options)

扫描局域网中指定类型的 mDNS 服务。

参数：

• options.serviceTypes (可选): 要扫描的服务类型数组，默认为常见服务类型
• options.timeout (可选): 扫描超时时间（毫秒），默认 5000ms
• options.success: 成功回调函数
• options.fail: 失败回调函数
• options.complete: 完成回调函数

返回值：

• ScanServicesResult 对象，包含设备列表和扫描结果

getMDNSDeviceList(options)

扫描所有常见服务类型，返回发现的设备列表。

参数：

• options.timeout (可选): 扫描超时时间（毫秒），默认 8000ms
• options.success: 成功回调函数
• options.fail: 失败回调函数
• options.complete: 完成回调函数

返回值：

• MDNSDeviceListResult 对象，包含设备列表和统计信息

getLocalIP()

获取本机 WiFi IP 地址。

返回值：

• string - 本机 IPv4 地址，如 "192.168.1.100"

isMDNSAvailable()

检查设备是否支持 mDNS 功能。

返回值：

• boolean - 是否支持 mDNS

📝 数据结构

MDNSDevice 设备信息

interface MDNSDevice {
  name: string;        // 设备名称（如：my-device.local）
  ip: string;          // 设备 IP 地址
  port: number;        // 服务端口号
  serviceType: string; // 服务类型（如：_http._tcp.local.）
  hostname: string;    // 主机名
  txtRecords: string[]; // 文本记录信息
}

错误代码说明

🔍 使用示例

完整的使用示例

import { scanServices, getLocalIP, isMDNSAvailable } from '@/uni_modules/wzq-mNDS';

// 1. 检查功能可用性
if (!isMDNSAvailable()) {
  console.error('设备不支持 mDNS 功能');
  return;
}

// 2. 获取本机 IP
const localIP = getLocalIP();
console.log('本机 IP:', localIP);

// 3. 扫描局域网设备
scanServices({
  serviceTypes: [
    '_http._tcp.local.',
    '_printer._tcp.local.',
    '_airplay._tcp.local.'
  ],
  timeout: 8000,
  success: (result) => {
    console.log('🎉 扫描成功！发现', result.count, '个设备');

    result.devices.forEach((device, index) => {
      console.log(`\n📱 设备 ${index + 1}:`);
      console.log('   名称:', device.name);
      console.log('   IP:', device.ip);
      console.log('   端口:', device.port);
      console.log('   服务类型:', device.serviceType);

      if (device.txtRecords.length > 0) {
        console.log('   附加信息:', device.txtRecords);
      }
    });
  },
  fail: (error) => {
    console.error('❌ 扫描失败:', error.errMsg);

    // 显示详细的网络诊断信息
    if (error.errCode === 9010001) {
      console.log('💡 请检查：');
      console.log('   - WiFi 是否已连接');
      console.log('   - 网络是否支持多播');
      console.log('   - 防火墙设置');
    }
  }
});

🛠️ 开发调试

日志输出

插件提供详细的日志输出，便于调试：

[MDNS] 网络状态检查通过，WiFi已连接
[MDNS] 本机网络: 192.168.1.100 接口: wlan0
[MDNS] 开始扫描服务类型: 3 超时: 5000 ms
[MDNS] ✅ 发现设备: iPhone.local IP: 192.168.1.101 端口: 80

网络诊断

当扫描失败时，插件会提供详细的网络诊断报告：

[MDNS] 🔍 详细网络诊断报告：
[MDNS]   网络状态: WiFi已连接
[MDNS]   本机IPv4: 192.168.1.100
[MDNS]   网络接口: wlan0
[MDNS]   估算子网: 192.168.1.0/24
[MDNS]   服务类型: _http._tcp.local.
[MDNS]   多播支持: 正常
[MDNS]   响应包: 仅来自本机（网络隔离）

⚠️ 注意事项

1. 网络隔离：某些路由器启用 AP 隔离功能，会导致设备间无法通信
2. 防火墙设置：确保防火墙允许 mDNS 流量（端口 5353）
3. WiFi 连接：必须在 WiFi 网络环境下使用
4. 权限要求：需要网络访问权限
5. Android 版本：需要 Android 6.0 及以上版本

🔧 故障排除

常见问题

Q: 扫描不到任何设备 A: 检查网络隔离设置，尝试使用手机热点测试

Q: 扫描超时 A: 增加 timeout 参数，检查网络多播功能

Q: 设备不支持 mDNS A: 确保设备运行 Android 6.0 及以上版本

Q: 网络权限问题 A: 检查应用是否具有网络访问权限

网络环境测试

建议在不同网络环境下测试：

1. 手机热点（最有效）
2. 关闭路由器的 AP 隔离功能
3. 启用路由器的多播/IGMP 功能

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件。

📞 支持

如有问题，请提交 Issue 或联系开发者。

版本: 1.0.0
最后更新: 2024-12-18