插件：网易云信音视频通话插件（呼叫组件）

场景：uni-app 项目中，多个页面/组件同时监听全局通话事件并上报通话记录

前言

在 uni-app 项目中集成网易云信通话插件后，我们需要在首页、聊天页等多个位置监听通话事件并上报通话记录。听起来简单的需求，实际落地时却踩了八层坑：

阶段	现象	根因
一	监听器"只活一次"	v-if 销毁 / SDK login 重置调度器 / 后台返回刷新
二	通话记录重复上报	removeEventListener 清全局 + 事件广播效应
三	标记被"自己人"清掉	setup 内部 remove 重置业务标记
四	原生引用莫名失效	顶层捕获的对象引用已过期
五	onShow 的背刺	清理方法夹带了业务状态重置

本文按真实时间线完整记录排查与修复过程。

---

一、监听器"只活一次"

1.1 v-if 销毁组件导致监听器被移除

现象：首页 HealthService 组件第一次通话有 onCallEnd 日志，之后再发起通话完全没有事件日志。

HealthService 在父页面中用 v-if 控制显示。组件被销毁时 onUnmounted 执行了 removeCallEventListeners()，全局监听全部清除；组件重建时监听器没有重新注册。

修复：将 v-if 改为 v-show，保持组件常驻内存。

教训：需要维持全局事件监听的组件，v-show 比 v-if 安全。v-if 的销毁/重建会触发 onUnmounted/onMounted，导致监听器反复注册和清除。

1.2 SDK login 重置事件调度器

现象：改用 v-show 后，某些页面（CallTest）监听正常，而 QnlHome 首页完全没有日志。

排查发现 QnlHome 的 onShow 中调用了 checkIMLoginStatus()，其内部链路最终走到 uni.$NECallKit.login()。login 完成后原生插件会重置事件调度器（NECallKitEvent），所有已注册的监听器全部丢失。CallTest 不调用此方法，所以不受影响。

修复：从页面生命周期中移除 checkIMLoginStatus() 调用。IM 登录已在 Login 页面完成，无需在 TabBar 页面重复调用。

教训：TabBar 页面的 onShow/onMounted 中绝对不能调用 yunxinCallKitLogin（含间接调用）。原生插件的 login 会重置事件调度器。

1.3 App 后台返回后事件调度器刷新

现象：用户从后台切回 App 后，原生事件调度器可能已被系统刷新，之前注册的 JS 监听器全部失效。

修复：采用关键时机强制重注册策略：

1. onMounted：首次注册
2. onShow：应对 App 后台返回（先 remove 再 setup）
3. 通话发起前：强制 remove + setup，确保监听器绑定在最新调度器上

const handleVideoCall = async () => {
  // ...前置检查...
  setupCallEventListeners();   // 强制重注册（内部先 remove 再 setup）
  callInitiatedByMe = true;    // 标记在 setup 之后设置（详见阶段三）
  neCallKit.toCallPage(...);
};

教训：uni-app 原生插件事件调度器可能在后台返回、SDK login 等场景被刷新，仅靠 onMounted 注册一次远远不够。

---

二、重复上报之谜

监听稳定后新问题出现：首页呼叫管理员后再到聊天页呼叫管理员，通话结束时出现两条上报：

[HealthService通话记录] 上报成功
[VideoCall] 上报成功

2.1 removeEventListener 不传回调清除全局监听器

项目中三个组件同时监听同一组全局通话事件：

组件	位置	职责
HealthService	首页子组件	首页呼叫管理员
video-call	TUIKit 聊天组件	聊天页呼叫
Friends	聊天页面	聊天页好友通话

每个组件的移除方法都这样写：

NECallKitEvent.removeEventListener('onCallEnd'); // 不传回调！

原生插件的 removeEventListener(eventName) 不传第二个参数时，会清除全局所有该事件的监听器。A 页面的操作会把 B 页面的监听器也清掉。

第一轮修复：各组件存储 handler 引用，removeEventListener 传具体回调，只清除自己的监听器。

let onCallEndHandler: ((e: any) => void) | null = null;

// 注册
onCallEndHandler = (e: any) => { ... };
NECallKitEvent.addEventListener('onCallEnd', onCallEndHandler);

// 移除时传引用
if (onCallEndHandler) {
  NECallKitEvent.removeEventListener('onCallEnd', onCallEndHandler);
}

然而，验证后仍然重复上报！

2.2 全局事件的"广播效应"

问题不在 onCallEnd，而在更早的事件。原生插件触发的全局事件是广播给所有监听器的：

video-call 发起通话
    ↓
onCallConnected 广播给所有监听器
    ↓
┌──────────────────────────────────────────┐
│ HealthService.onCallConnected → 触发！   │
│   → callRecord.calleeId 被填充           │
│                                          │
│ video-call.onCallConnected → 触发！      │
│   → callRecord.calleeId 被填充           │
└──────────────────────────────────────────┘
    ↓
onCallEnd 广播
    ↓
HealthService: calleeId 有值 → 上报！❌
video-call:   calleeId 有值 → 上报！✓

HealthService 的 onCallConnected 也会收到 video-call 发起的通话事件，导致其 callRecord 被填充。仅靠 calleeId 守卫无法区分"谁发起了通话"。

第二轮修复：引入 callInitiatedByMe 发起方标记。

let callInitiatedByMe = false;

// 发起通话时标记
const handleVideoCall = async () => {
  callInitiatedByMe = true;
  neCallKit.toCallPage(...);
};

// 全局事件 handler 中校验
onCallEndHandler = (e: any) => {
  if (callInitiatedByMe) {
    reportCallRecordData(e, callRecord.value, 'HealthService');
    callInitiatedByMe = false;
    callRecord.value = {};
  } else {
    console.log('[HealthService] 非本组件发起的通话，跳过上报');
  }
};

三个组件统一实施后，重复上报彻底解决。

---

三、标记被"自己人"清掉

重复上报修复后，聊天页多次通话后 onCallEnd 日志显示"非本组件发起的通话，跳过上报"——明明是从本组件发起的！

3.1 setup 内部的"自相矛盾"

为了让每次通话前监听器都绑定在最新调度器上，handleCall 中添加了强制重注册：

const handleCall = () => {
  callInitiatedByMe = true;     // ① 设置标记
  setupCallEventListeners();    // ② 强制重注册
  neCallKit.toCallPage(...);    // ③ 发起通话
};

但 setupCallEventListeners() 内部第一步就调用了 removeCallEventListeners()，而后者会重置 callInitiatedByMe = false。执行顺序变成了：

① callInitiatedByMe = true
② setupCallEventListeners()
   → removeCallEventListeners()
      → callInitiatedByMe = false  ← 标记被自己清掉了！
③ toCallPage()
④ onCallEnd → callInitiatedByMe 为 false → 跳过上报 ❌

修复：将 callInitiatedByMe = true 移到 setupCallEventListeners() 之后。

教训：当 setup 内部包含 remove（先清后注模式）时，业务标记的设置时机必须在 setup 之后，否则会被内部的清理逻辑覆盖。

---

四、原生引用莫名失效

修复标记时序后，聊天页首次通话正常，但多次通话后又出现监听丢失。而好友详情页多次通话却不受影响。

4.1 顶层一次性捕获 NECallKitEvent 导致引用过期

video-call 组件在 <script setup> 顶层一次性捕获了 NECallKitEvent：

const NECallKitEvent = (uni as any).$NECallKitEvent; // 组件创建时捕获

通话结束从原生通话页返回后，原生事件调度器可能被系统刷新，uni.$NECallKitEvent 指向了新的实例，但组件中保存的仍是旧引用。通过旧引用注册的监听器自然无法收到事件。

而 HealthService 使用了动态获取函数 getNECallKitEvent()，每次都取最新实例，所以不受影响。

修复：所有组件统一改为动态获取。

// ❌ 旧方式：顶层一次性捕获，引用可能过期
const NECallKitEvent = (uni as any).$NECallKitEvent;

// ✅ 新方式：每次调用取最新实例
const getNECallKitEvent = () => (uni as any).$NECallKitEvent;

const setupCallEventListeners = () => {
  const NECallKitEvent = getNECallKitEvent(); // 取最新的
  if (!NECallKitEvent) return;
  // ...注册监听器...
};

教训：uni-app 原生插件的对象引用可能在 App 后台返回、通话页返回等场景被刷新。永远不要假设顶层捕获的引用始终有效，应该通过 getter 函数动态获取。

---

五、onShow 的背刺

以上修复完成后，首页通话仍然出现"非本组件发起的通话"。

5.1 removeCallEventListeners 重置了业务标记

通话结束从原生页返回后，QnlHome 的 onShow 触发：

onShow(() => {
  healthServiceRef.value?.removeCallEventListeners();  // 清除旧监听
  healthServiceRef.value?.setupCallEventListeners();   // 注册新监听
});

问题在于 removeCallEventListeners() 中有一行 callInitiatedByMe = false。执行流程：

通话结束，从原生页返回
  → onShow 触发
    → removeCallEventListeners()
      → callInitiatedByMe = false  ← 标记被清掉！
    → setupCallEventListeners()
  → onCallEnd 触发（稍后）
    → callInitiatedByMe 为 false → 跳过上报 ❌

修复：removeCallEventListeners() 只负责清理监听器引用，不应重置业务状态标记。callInitiatedByMe 仅在两处重置：

1. onCallEnd handler 中上报成功后
2. onUnmounted 中组件销毁时

const removeCallEventListeners = () => {
  // ...移除监听器...
  // 不重置 callInitiatedByMe —— 它是业务状态，与监听器注册状态无关
};

onUnmounted(() => {
  removeCallEventListeners();
  callInitiatedByMe = false;  // 组件销毁时才需要重置
});

教训：remove 类方法应该只负责"清理资源"，不应该夹带"重置业务状态"的逻辑。基础设施层的清理和业务层的状态管理必须解耦。

---

六、接听端验证

一切修复到位后，测试接听端场景：别人呼叫本设备，各组件正确忽略了所有事件：

[HealthService] onReceiveInvited: {"callerAccount":"2042877072166264834"}
[HealthService] 非本组件发起的通话，忽略 onReceiveInvited

这是预期行为。callInitiatedByMe 守卫的设计目的就是：只有本组件主动发起的通话才响应事件和上报。接听端没有发起通话，callInitiatedByMe = false，所有事件被正确忽略。

---

七、工具化封装

随着三个组件都接入通话监听上报，重复代码越来越多。按照"逻辑解耦、工具先行"的原则，将上报逻辑抽取为公共工具模块 src/utils/callRecordReporter.ts：

方法	职责
getLocalDateTime()	获取本地格式化时间
calculateDuration()	计算通话时长
mapCallEndCode()	SDK 结束码映射为业务状态
getLocalUserId()	获取本地用户 ID
reportCallRecordData()	核心上报函数

页面/组件只负责：监听事件注册、callRecord 状态维护、callInitiatedByMe 标记管理。

原则：页面只做监听和状态维护，上报逻辑全部走工具模块。

---

最终方案总结

架构全景

┌─────────────────────────────────────────────────────────┐
│                    全局通话事件总线                        │
│              (NECallKitEvent / globalEvent)              │
│         ⚠️ 每次通过 getNECallKitEvent() 动态获取          │
└──────────┬──────────────────┬──────────────────┬────────┘
           │                  │                  │
     ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
     │HealthService│    │ video-call │     │  Friends   │
     │            │     │            │     │            │
     │ callInit-  │     │ callInit-  │     │ callInit-  │
     │ iatedByMe  │     │ iatedByMe  │     │ iatedByMe  │
     │            │     │            │     │            │
     │ handler    │     │ handler    │     │ handler    │
     │ 引用隔离   │     │ 引用隔离   │     │ 引用隔离   │
     │            │     │            │     │            │
     │ 通话前     │     │ 通话前     │     │ 通话前     │
     │ 强制重注册 │     │ 强制重注册 │     │ 强制重注册 │
     └─────┬──────┘     └─────┬──────┘     └─────┬──────┘
           │                  │                  │
           └──────────────────┼──────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │ callRecordReporter │
                    │    (公共工具)      │
                    └───────────────────┘

  callInitiatedByMe 重置时机：
    ✅ onCallEnd 上报成功后
    ✅ onUnmounted 组件销毁时
    ❌ removeCallEventListeners 中不重置（解耦基础设施与业务状态）

八大修复要点

#	问题	修复
1	v-if 销毁组件导致监听丢失	改用 v-show 保持组件常驻
2	SDK login 重置事件调度器	从页面生命周期中移除 IM 登录调用
3	App 后台返回后监听失效	onShow + 通话发起前强制重注册
4	removeEventListener 清除全局监听器	存储 handler 引用，传具体回调移除
5	全局事件广播导致非发起方误上报	引入 callInitiatedByMe 发起方标记
6	setup 内部 remove 重置业务标记	callInitiatedByMe = true 移到 setup 之后
7	顶层捕获 NECallKitEvent 引用过期	改为 getNECallKitEvent() 动态获取
8	removeCallEventListeners 重置业务状态	清理方法不重置业务标记，仅在 onCallEnd/onUnmounted 重置

适用场景

这套方案适用于任何需要在多个组件/页面中监听同一全局事件、且只有事件发起方需要响应的场景：

• 音视频 SDK 的通话事件监听
• IM 消息事件的页面级处理
• 原生插件的全局回调分发

---

写在最后

这个问题的排查经历了五轮迭代、八个根因，从表面的"监听丢失"到深层的"重复上报"，再到"标记时序"、"引用过期"、"状态耦合"，每一层修复都暴露了更深层的问题。总结三条核心教训：

1. 全局事件总线 + 多组件监听 = 必须考虑事件归属

当多个组件监听同一全局事件时，不能假设"我的 callRecord 有值就是我发起的"——全局事件是广播的，所有组件都会收到。必须通过显式标记区分发起方。

2. 原生插件引用 = 不可信的"一次性快照"

原生插件的对象引用可能在后台返回、通话页返回等场景被刷新。永远不要假设顶层捕获的引用始终有效，应该通过 getter 函数动态获取最新实例。

3. 清理方法不应夹带业务逻辑

remove 类方法只负责清理资源，不应重置业务状态。基础设施层的清理和业务层的状态管理必须解耦，否则会出现"清理资源时意外清掉业务上下文"的隐蔽 Bug。