wiliwili全平台故障诊断指南：从用户困境到代码级解决方案

前言：三个典型用户困境

场景一：Switch玩家小王在周末想通过wiliwili观看直播放松，却发现启动时卡在白屏界面，反复重启后仍无法进入主界面。

场景二：PSVita用户小李在使用wiliwili观看视频时，手柄突然失去响应，无法进行任何操作，只能强制关机。

场景三：PC用户小张在更新wiliwili后，发现视频播放时没有声音，尝试调整音量和更换视频均无效。

P0级故障：初始化失败

【E001】启动白屏/崩溃

问题场景：用户启动wiliwili后，屏幕一直显示白屏或直接崩溃退出，无法进入应用主界面。

故障定位：从[wiliwili/source/main.cpp]代码中可以看到，当应用初始化失败时，会输出"Unable to init application"的错误信息。

解决方案：

🔧 方案一：清除配置文件

1. 进入设备文件管理器
2. 导航到应用配置目录（不同设备路径不同）
   • PC：C:\Users[用户名]\AppData\Roaming\wiliwili
   • Switch：sdmc:/wiliwili/config
   • PSVita：ux0:/data/wiliwili/config
3. 删除config.ini文件
4. 重新启动应用

🔧 方案二：重新安装应用

1. 卸载当前版本wiliwili
2. 从官方渠道下载最新版本
3. 安装时选择"清除旧数据"选项

预防措施： ⚠️ 定期备份配置文件，避免频繁更新系统或修改系统文件。

适用设备：PC/PSVita/PS4/Switch

底层原理：应用初始化流程

wiliwili的初始化过程主要包括：配置文件加载、系统环境检测、资源初始化等步骤。当任何一个环节出现问题，都会导致初始化失败。配置文件损坏是最常见的原因，因为它存储了应用的关键设置信息，如窗口大小、账号信息等。

P1级故障：网络连接问题

【E101】WebSocket连接失败

问题场景：用户尝试观看直播时，提示"无法连接到直播服务器"，视频区域显示黑屏。

故障定位：在[wiliwili/source/api/danmaku_live.cpp]中，如果WebSocket（实时数据传输协议）连接失败，会记录"(LiveDanmaku) 无法创建WebSocket连接"的错误日志。

解决方案：

🔧 方案一：网络诊断

1. 进入设置界面
2. 选择"网络设置"
3. 点击"网络诊断"按钮
4. 根据诊断结果修复网络问题

🔧 方案二：手动设置DNS

1. 进入设备网络设置
2. 将DNS服务器手动设置为公共DNS
   • 114.114.114.114
   • 8.8.8.8
3. 重启wiliwili应用

预防措施： ⚠️ 避免使用公共Wi-Fi网络观看直播，这类网络通常有严格的防火墙限制。

适用设备：全平台

P2级故障：媒体播放问题

【E201】视频加载失败

问题场景：用户选择视频后，加载进度条一直处于加载状态，无法开始播放。

故障定位：在[wiliwili/source/utils/image_helper.cpp]中，当视频封面加载失败时，会输出"Failed to load image"的错误提示。

解决方案：

🔧 方案一：调整视频质量

1. 进入设置界面
2. 选择"播放设置"
3. 将视频质量从"自动"改为"720p"或更低
4. 重启应用后尝试播放

🔧 方案二：更换视频编码

1. 进入设置界面
2. 选择"高级设置"
3. 找到"视频编码"选项
4. 尝试切换不同的编码格式（H.264/H.265）

预防措施： ⚠️ 根据设备性能选择合适的视频质量，老旧设备建议使用较低画质。

适用设备：全平台

【E202】播放卡顿/缓冲频繁

问题场景：视频播放过程中频繁卡顿，缓冲时间过长，影响观看体验。

故障定位：在[wiliwili/source/activity/setting_activity.cpp]中有关于视频缓冲和性能优化的相关设置。

解决方案：

🔧 方案一：调整缓冲设置

1. 进入设置界面
2. 选择"播放设置"
3. 增加"预缓冲时长"至10秒以上
4. 启用"智能预加载"功能

🔧 方案二：限制帧率

1. 进入设置界面
2. 选择"高级设置"
3. 启用"LIMITED_FPS"选项
4. 将帧率限制为30fps

预防措施： ⚠️ 在网络条件不佳时，提前下载视频而非在线观看。

适用设备：PSVita/PS4/Switch（性能受限设备）

P3级故障：手柄控制问题

【E301】手柄按键无响应

问题场景：连接手柄后，按键操作无响应或响应错误，无法正常导航菜单。

故障定位：在[wiliwili/source/activity/setting_activity.cpp]中有关于手柄按键映射和ABXY键位交换的设置实现。

解决方案：

🔧 方案一：重新映射按键

1. 进入设置界面
2. 选择"控制器设置"
3. 选择"按键映射"
4. 根据手柄类型选择合适的预设方案

🔧 方案二：启用ABXY键位交换

1. 进入设置界面
2. 选择"控制器设置"
3. 启用"APP_SWAP_ABXY"选项
4. 测试按键响应是否正常

预防措施： ⚠️ 使用官方推荐的手柄型号，第三方手柄可能存在兼容性问题。

适用设备：PSVita/PS4/Switch

交叉故障排除

【X001】跨设备同步问题

问题场景：用户在多台设备上使用wiliwili，发现收藏和观看历史无法同步。

解决方案：

🔧 方案一：手动导出/导入数据

1. 在原设备上进入设置
2. 选择"数据管理"
3. 点击"导出数据"，保存到外部存储
4. 在新设备上导入该数据文件

🔧 方案二：启用云同步

1. 确保所有设备都已登录同一账号
2. 进入设置界面
3. 选择"云同步"选项
4. 启用"自动同步"功能

适用设备：全平台

开发者视角：代码级调试建议

调试初始化问题

如果遇到持续的初始化问题，可以查看[wiliwili/source/main.cpp]中的main函数，添加详细的日志输出，定位具体的初始化失败点。关键代码段如下：

// 伪代码示例
int main(int argc, char* argv[]) {
    log_debug("Starting application initialization");
    
    if (!init_config()) {
        log_error("Failed to initialize config");
        return -1;
    }
    
    if (!init_network()) {
        log_error("Failed to initialize network");
        return -1;
    }
    
    // 更多初始化步骤...
    
    log_debug("Application initialized successfully");
    return run_app();
}

网络问题调试

对于网络连接问题，可以在[wiliwili/source/api/util/http.cpp]中添加网络请求日志，检查请求和响应详情，帮助定位网络问题根源。

结语

wiliwili作为一款跨平台的B站客户端，在不同设备上可能会遇到各种问题。通过本文介绍的故障诊断方法，大多数常见问题都可以得到解决。如果遇到本文未覆盖的问题，建议查看项目的官方文档或在社区寻求帮助。

希望本文能够帮助您更好地使用wiliwili，享受流畅的B站视频观看体验！