wiliwili故障定位指南

wiliwili作为专为手柄控制设计的第三方跨平台B站客户端，支持PC全平台、PSVita、PS4和Nintendo Switch等多种设备。本指南采用"问题现象→原因分析→解决方案→预防措施"框架，帮助用户快速定位并解决99% 的常见问题。

图1：wiliwili主界面展示

【初始化故障】启动白屏

问题现象：应用启动后屏幕持续白色，无任何响应。

原因分析：

• 配置文件损坏或缺失
• init_application()函数执行失败
• 资源文件加载异常

解决方案：

1. 检查配置文件完整性：通过设置界面打开配置目录，验证配置文件是否存在且格式正确
2. 清除应用缓存：删除配置目录下的cache文件夹
3. 验证方法：重启应用观察是否正常显示加载界面

预防措施：

• 定期备份配置文件
• 避免异常关闭应用程序

快速自检清单： ✅ 配置目录存在且可访问 ✅ 配置文件大小正常（非0字节） ✅ 应用目录具有读写权限

【网络连接】WebSocket连接失败

问题现象：无法加载直播内容，提示"连接服务器失败"。

原因分析：

• WebSocket（一种支持双向通信的网络协议）连接建立失败
• 网络环境限制WebSocket通信
• DNS解析异常

解决方案：

1. 运行网络诊断工具：在设置界面点击"网络检查器"按钮
2. 修改DNS设置：手动配置公共DNS服务器（如114.114.114.114）
3. 验证方法：检查设置界面网络状态显示"已连接"

预防措施：

• 使用稳定网络环境
• 定期检查网络设置

快速自检清单： ✅ 其他网络应用工作正常 ✅ 防火墙未阻止应用网络访问 ✅ DNS服务器地址配置正确

【媒体播放】视频加载失败

问题现象：选择视频后持续缓冲或显示"加载失败"提示。

原因分析：

• 视频资源链接失效
• 不支持的视频编码格式
• load_image()函数执行异常

解决方案：

1. 调整视频编码设置：在设置中修改"视频编码"选项为H.264
2. 切换视频质量：降低清晰度至720p或以下
3. 验证方法：播放测试视频确认画面正常显示

预防措施：

• 保持应用版本更新
• 根据设备性能选择合适的视频质量

快速自检清单： ✅ 网络带宽满足1Mbps以上 ✅ 视频格式为MP4或FLV ✅ 存储空间剩余大于1GB

图2：wiliwili视频播放界面

【界面显示】字体显示异常

问题现象：界面文字出现乱码或方块字符。

原因分析：

• 系统字体缺失
• UI缩放比例设置不当
• 字体渲染引擎初始化失败

解决方案：

1. 调整UI缩放：在设置中选择"UI缩放"为1080p适配模式
2. 安装系统字体：确保设备已安装SimHei或Microsoft YaHei字体
3. 验证方法：重启应用后检查文字显示正常

预防措施：

• 不要修改应用字体配置文件
• 保持系统字体库完整

快速自检清单： ✅ 系统字体文件存在 ✅ UI缩放比例与屏幕分辨率匹配 ✅ 应用主题设置为默认值

【手柄控制】按键无响应

问题现象：手柄连接后按键操作无反应。

原因分析：

• 按键映射配置错误
• 手柄驱动未正确加载
• ABXY键位交换功能开启

解决方案：

1. 重置按键映射：在设置中选择"重置按键配置"
2. 切换ABXY键位：关闭"ABXY键位交换"选项
3. 验证方法：进入设置的"手柄测试"界面检查按键响应

预防措施：

• 使用官方支持的手柄设备
• 避免同时连接多个输入设备

快速自检清单： ✅ 手柄已正确连接设备 ✅ 手柄电量充足 ✅ 按键映射配置文件未损坏

社区支持渠道

遇到本指南未覆盖的问题时，可通过以下渠道获取支持：

• 项目Issue跟踪：提交详细问题描述和日志信息
• 社区讨论：参与项目讨论区交流解决方案
• 版本更新：通过设置中的"检查更新"功能获取最新修复版本

wiliwili作为开源项目，欢迎用户贡献问题解决方案和代码改进。