zyt/DIAGNOSE_INIT_FAIL.md

诊断TUICallKit初始化失败问题

当前错误

ERROR_INIT_FAIL: -1201
API<getDeviceList>: init or login is not complete
TUICallEngine 初始化登录未完成，需要在 init 或 login 完成后使用此 API

可能的原因

1. UserSig无效（最可能）⭐

症状：

• init方法调用成功，但实际登录失败
• 等待再久也没用
• 控制台可能有IM登录失败的错误

原因：

• SDKAppID不正确（使用了TRTC的而非IM的）
• SecretKey不正确
• UserSig生成算法有误
• IM服务未开通

解决方案：运行测试脚本验证

cd server
php test_usersig.php

2. SDKAppID类型错误

症状：

• 报错提示SDKAppID必须是Number

原因：

• 传递的是字符串而非数字

解决方案：已修复，使用 Number(res.sdkAppId)

3. 网络连接问题

症状：

• 长时间无响应
• 控制台有网络错误

原因：

• 无法连接到腾讯云服务器
• 防火墙阻止连接
• HTTPS证书问题

解决方案：

• 检查网络连接
• 使用HTTPS或localhost
• 检查浏览器控制台的网络错误

4. 等待时间不够

症状：

• 偶尔成功，偶尔失败

原因：

• 初始化需要时间，等待不够

解决方案：已修复，等待4秒

诊断步骤

步骤1：验证配置是否正确

运行测试脚本：

cd server
php test_usersig.php

预期输出：

=== 腾讯云IM UserSig测试 ===

SDKAppID: 1600127710
SecretKey长度: 64
SecretKey前10位: 8a6b3ce533...

✅ UserSig生成成功！
✅ UserSig验证成功！
✅ IM账号导入成功！

如果失败：

• 检查 server/.env 中的配置
• 确认SDKAppID是IM应用的，不是TRTC应用的
• 确认SecretKey正确

步骤2：检查浏览器控制台

打开浏览器开发者工具（F12），查看：

Console标签

查找以下错误：

// ❌ UserSig错误
Error: login failed, error code: 70003
Error: UserSig is invalid

// ❌ SDKAppID错误
Error: SDKAppID must be Number

// ❌ 网络错误
Error: Failed to fetch
Error: Network error

Network标签

查找请求到 tim.qq.com 或 trtc.io 的请求：

• 如果没有请求：网络被阻止
• 如果请求失败：检查错误信息
• 如果请求成功但返回错误：检查响应内容

步骤3：检查IM登录状态

在浏览器控制台执行：

// 检查TUICallKit状态
console.log('TUICallKit:', TUICallKitServer)

// 尝试获取登录状态（如果有这个API）
// 注意：这可能会报错，但能帮助诊断
try {
    const status = await TUICallKitServer.getLoginStatus()
    console.log('登录状态:', status)
} catch (e) {
    console.error('获取状态失败:', e)
}

步骤4：使用腾讯云官方工具验证

访问：https://console.cloud.tencent.com/im/tool-usersig

1. 输入SDKAppID
2. 输入SecretKey
3. 输入UserID（如：doctor_1）
4. 点击"生成UserSig"

如果生成失败：

• SDKAppID或SecretKey错误
• 需要在腾讯云控制台确认正确的值

如果生成成功：

• 复制生成的UserSig
• 在浏览器控制台手动测试：

await TUICallKitServer.init({
    userID: 'doctor_1',
    userSig: '从官方工具复制的UserSig',
    SDKAppID: 1600127710
})

如果这样能成功，说明后端生成的UserSig有问题。

常见问题和解决方案

问题1：ErrorCode 70003 - UserSig非法

原因：

• SDKAppID是TRTC的，不是IM的
• SecretKey不匹配

解决：

1. 登录腾讯云控制台
2. 进入：即时通信IM > 应用列表
3. 确认SDKAppID（不是TRTC的）
4. 进入应用详情 > 密钥管理
5. 复制正确的SecretKey
6. 更新 server/.env：

[TRTC]
SDK_APP_ID = "正确的IM应用SDKAppID"
SECRET_KEY = "正确的SecretKey"
ENABLE = "true"

问题2：一直等待，没有任何错误

原因：

• 网络连接问题
• 防火墙阻止

解决：

1. 检查是否使用HTTPS或localhost
2. 检查浏览器控制台的Network标签
3. 尝试禁用防火墙/代理

问题3：偶尔成功，偶尔失败

原因：

• 等待时间不够
• 网络不稳定

解决：

1. 增加等待时间到6秒
2. 检查网络稳定性

问题4：前端报错但后端测试成功

原因：

• 前端传递的参数有误
• 类型转换问题

解决：

1. 检查前端传递的参数：

console.log('传递给init的参数:', {
    userID: res.userId,
    userSig: res.userSig,
    SDKAppID: Number(res.sdkAppId),
    types: {
        userID: typeof res.userId,
        userSig: typeof res.userSig,
        SDKAppID: typeof Number(res.sdkAppId)
    }
})

2. 确保所有参数正确：
   • userID: 字符串，如 "doctor_1"
   • userSig: 字符串，长度约200-300
   • SDKAppID: 数字，如 1600127710

临时解决方案

如果无法立即解决，可以尝试：

方案A：增加等待时间

// 增加到6秒或更长
await new Promise(resolve => setTimeout(resolve, 6000))

方案B：添加重试机制

async function initWithRetry(maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            await TUICallKitServer.init({ ... })
            await new Promise(resolve => setTimeout(resolve, 4000))
            
            // 尝试调用一个API验证是否初始化成功
            await TUICallKitServer.call({ ... })
            return true
        } catch (e) {
            console.log(`第${i + 1}次尝试失败:`, e)
            if (i === maxRetries - 1) throw e
            await new Promise(resolve => setTimeout(resolve, 2000))
        }
    }
}

方案C：使用官方示例代码

参考腾讯云官方文档的示例代码，确保实现方式正确。

下一步行动

立即执行

1. ✅ 运行 php server/test_usersig.php
2. ✅ 检查浏览器控制台错误
3. ✅ 使用腾讯云官方工具验证UserSig

如果测试脚本失败

说明配置有问题，需要：

1. 确认SDKAppID和SecretKey
2. 更新 server/.env
3. 重新测试

如果测试脚本成功但前端失败

说明前端传递参数有问题，需要：

1. 检查前端传递的参数
2. 添加详细的日志
3. 对比后端生成的UserSig和前端收到的UserSig

如果都成功但仍然失败

可能是网络或浏览器问题，需要：

1. 尝试不同的浏览器
2. 检查网络连接
3. 尝试使用HTTPS

联系支持

如果以上方法都无法解决，可以：

1. 查看腾讯云IM控制台的日志
2. 联系腾讯云技术支持
3. 在腾讯云开发者社区提问

提供以下信息：

• SDKAppID
• 错误信息截图
• 浏览器控制台日志
• 测试脚本输出

---

关键要点：先运行 php server/test_usersig.php 验证配置是否正确！🔍