👋 你好，欢迎来到我的博客！我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者，正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来，也为了和更多同路人互相启发，我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向：ArkTS 语言基础、HarmonyOS 原生应用（Stage 模型、UIAbility/ServiceAbility）、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战，以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏：从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘，让每篇都有可落地的代码与方法论。
  💡 我相信：写作是把知识内化的过程，分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长，欢迎关注我，一起交流进步！🚀

先问你一个关键问题（不影响你先看正文🙂）

你现在做的是 HarmonyOS NEXT（华为开发者文档体系） 还是 OpenHarmony（开源发行版）？以及你要发现的是 可信设备（已认证/同生态） 还是 周边不可信设备？

我下面会按“主流通用路径”写，你回我一句我再把权限点、接口差异和坑位对准你的系统版本。🧭

1）DeviceManager 使用：把它当“设备管理入口”，别当“万能扫描器”🔧

在 HarmonyOS / HarmonyOS NEXT 的 ArkTS API 里，设备管理能力集中在 @ohos.distributedDeviceManager：

• 创建/释放 DeviceManager 实例
• 查询可信设备列表（available device list）
• 发起发现（startDiscovering/stopDiscovering）
• 监听设备上下线（deviceStateChange）
• 监听发现成功/失败（discoverSuccess/discoverFailure）
  这些能力在官方 API 参考里是成套列出来的。

1.1 最小可用代码：创建管理器 + 发现 + 拿列表 + 监听事件（建议你照抄）

import { distributedDeviceManager } from '@kit.DistributedServiceKit'
import { hilog } from '@kit.PerformanceAnalysisKit'

const TAG = 'DM'

let dm: distributedDeviceManager.DeviceManager | null = null

export function initDeviceManager(bundleName: string) {
  dm = distributedDeviceManager.createDeviceManager(bundleName)

  // 1) 监听设备上下线（可信设备上下线变化）
  dm.on('deviceStateChange', (data) => {
    hilog.info(0x0000, TAG, `deviceStateChange: ${JSON.stringify(data)}`)
  })

  // 2) 监听发现成功：发现到“周边不可信设备”时常用
  dm.on('discoverSuccess', (data) => {
    hilog.info(0x0000, TAG, `discoverSuccess: ${JSON.stringify(data)}`)
  })

  // 3) 监听发现失败：排查必看
  dm.on('discoverFailure', (data) => {
    hilog.error(0x0000, TAG, `discoverFailure: ${JSON.stringify(data)}`)
  })

  // 4) 服务死亡（系统侧服务异常重启等）
  dm.on('serviceDie', () => {
    hilog.error(0x0000, TAG, 'serviceDie: DeviceManager service died')
  })
}

export function startDiscover() {
  if (!dm) return
  // 具体参数（订阅ID/发现参数）以你SDK版本为准
  dm.startDiscovering()
}

export async function dumpTrustedDevices() {
  if (!dm) return
  const list = await dm.getAvailableDeviceList() // 或 getAvailableDeviceListSync
  hilog.info(0x0000, TAG, `available devices: ${JSON.stringify(list)}`)
}

export function releaseDeviceManager() {
  if (!dm) return
  distributedDeviceManager.releaseDeviceManager(dm)
  dm = null
}

注意：官方把“发现周边不可信设备”和“查询可信设备列表”明确区分成两类能力：发现是“找周边”，available list 是“可信设备集合”。

2）设备筛选策略：别“扫到啥算啥”，你得像个产品一样挑设备😤

我建议你把筛选拆成两层：硬筛选（一定不要）+ 软筛选（优先级排序）。

2.1 硬筛选（建议默认就做）

• 过滤本机：networkId / deviceId 等于本机的直接跳过（否则你会发现“自己”🤣）
• 过滤匿名/空字段设备：字段不完整往往是发现过程的“半成品”
• 过滤不支持目标业务的设备类型：比如你只做“手机 ↔ 平板协同”，电视/穿戴就别进列表

DeviceManager 的设备信息结构里包含诸如 deviceName、deviceType、networkId 等基础字段（不同版本字段略有差异，但核心信息一致）。

2.2 软筛选（强烈推荐，体验差距会很大）

• 信号强度/连接质量（如果你的发现链路能拿到）：优先近的、稳定的
• 名称规则：比如只展示包含你品牌前缀的设备（更像“一个生态”）
• 最近使用：把上次连接成功的设备置顶（用户会觉得“它懂我”🙂）

2.3 一个“真实项目可用”的筛选函数（示意）

type Dev = { deviceName?: string, deviceType?: number, networkId?: string }

export function filterAndSortDevices(devices: Dev[]) {
  const filtered = devices
    .filter(d => !!d.networkId && d.networkId.length > 0)
    .filter(d => (d.deviceName ?? '').trim().length > 0)
    .filter(d => d.deviceName !== 'Unknown')

  // 示例：把包含“Pad”的置顶（你按产品定义规则）
  filtered.sort((a, b) => {
    const ap = (a.deviceName ?? '').includes('Pad') ? 1 : 0
    const bp = (b.deviceName ?? '').includes('Pad') ? 1 : 0
    return bp - ap
  })
  return filtered
}

3）设备状态监听：别只靠“发现回调”，上下线要靠 deviceStateChange 👂

很多同学会把“发现设备”当成“设备在线”，然后踩雷：

• 发现到了，但用户没认证/不可信
• 发现到了，但转头就离线
• 发现到了，但真正的“可信设备列表”压根没变化

正确姿势是两条链路并行：

1. 发现链路（discoverSuccess / discoverFailure）：负责找周边、引导认证
2. 可信链路（getAvailableDeviceList + deviceStateChange）：负责业务真正可用的设备集

官方 API 参考把这两类事件都列出来了。

4）常见问题排查：扫不到/回调不来/列表为空，按这个顺序查（非常救命）🧯

4.1 先查“你用的到底是哪套 API”

你可能同时见过两套名字很像的东西：

• @ohos.distributedDeviceManager（更偏“分布式设备管理”新入口，HarmonyOS API参考在更新）
• 以及一些旧示例/文章里出现的 @ohos.distributedHardware.deviceManager / startDeviceDiscovery 等（OpenHarmony历史版本里常见）

如果你项目是 NEXT/较新 SDK，建议优先对齐 @ohos.distributedDeviceManager 的事件与方法集合（discoverSuccess/deviceStateChange 等），别混用导致“你以为注册了回调，其实监听的是另一个模块”。

4.2 查权限与系统限制：有些发现接口在某些版本/场景会限制“非系统应用”

在 OpenHarmony 的一些版本与场景里，使用 startDeviceDiscovery 发现失败，回调 reason=1008（DM_NOT_SYSTEM_APP）表示“调用方不是系统应用”，需要系统级签名/配置才能调用该能力。

这类问题最坑：你代码没错、设备也没问题，但就是“权限身份不够”。如果你在 OpenHarmony 侧遇到类似报错，先把错误码对上再决定是走系统应用能力还是换能力路径。

4.3 查设备基础条件（别笑，真有人忘）

• 两台设备是否处于允许分布式的环境（网络/蓝牙/相关开关）
• 是否在同一局域网/可发现范围
• 设备是否已完成必要的认证/绑定（你要走“可信设备列表”就必须有信任关系）
  DeviceManager 组件本身也强调它负责“认证组网、发现、监听”等能力。

4.4 查回调注册时机：你是不是注册完立刻被释放了？😅

典型翻车：

• 页面 onAppear 里 create + on + start
• 页面一切换，aboutToDisappear 里 release
• 结果 discovery 还没跑完，dm 被你释放了

建议：

• 把 DeviceManager 放到更稳定的生命周期里（比如 UIAbility/单例服务层）
• 至少保证：stopDiscovering + off 监听 + release 有序执行

4.5 查“你期待的列表是不是拿错了”

• discoverSuccess：你发现的是“周边可发现设备”（可能不可信）
• getAvailableDeviceList：你拿的是“可信设备集合”（业务可用）
  两者不一致是正常现象，别把它当 bug。

结尾：设备发现做得好不好，用户体感差一整个等级🙂

说到底，分布式设备发现不是“扫到就完事”，而是：

• 发现链路要稳（别疯狂失败）
• 筛选策略要像产品（别把用户当测试员）
• 状态监听要可靠（别误判在线）
• 排查链路要清晰（别靠玄学）

📝 写在最后

如果你觉得这篇文章对你有帮助，或者有任何想法、建议，欢迎在评论区留言交流！你的每一个点赞 👍、收藏 ⭐、关注 ❤️，都是我持续更新的最大动力！

我是一个在代码世界里不断摸索的小码农，愿我们都能在成长的路上越走越远，越学越强！

感谢你的阅读，我们下篇文章再见～👋

✍️ 作者：某个被流“治愈”过的 移动端 老兵
📅 日期：2025-11-05
🧵 本文原创，转载请注明出处。