wiliwili 故障排查指南：手柄控制 B 站客户端的 10 个快速自检方法
【免费下载链接】wiliwili第三方B站客户端，目前可以运行在PC全平台、PSVita、PS4 、Xbox 和 Nintendo Switch上项目地址: https://gitcode.com/GitHub_Trending/wi/wiliwili
wiliwili 是专为手柄控制设计的第三方跨平台 B 站客户端，可运行在 PC 全平台、PS Vita、PS4、Xbox 和 Nintendo Switch 上。本指南覆盖启动失败、连接异常、视频播放卡顿、界面显示、手柄按键故障等 10 个高频问题，帮你几分钟内自行定位并处理。
3 分钟快速自检
先对照现象缩小方向，再进入对应章节处理：
| 现象 | 优先检查 | 常见原因 | 下一步操作 |
|---|---|---|---|
| 启动报错、初始化失败 | 安装包与平台是否匹配 | 版本下载错、文件不完整 | 重新下载对应平台包并安装 |
| 启动后长时间黑屏（Switch） | 内存卡配置目录 | 配置文件损坏 | 删除 config/wiliwili 目录后重新进入 |
| 首页/搜索内容加载不出来 | 网络连通性、DNS | 网络受限、DNS 异常 | 用设置内网络诊断，再调整 DNS |
| 直播弹幕不动 | WebSocket 连接 | 代理或网络导致断开 | 关闭代理后重新进入直播间 |
| 视频无法播放、加载失败 | 资源链接与编解码设置 | 链接失效、编码不兼容 | 刷新，或更换清晰度/编码 |
| 播放卡顿、频繁缓冲 | 视频质量与带宽 | 清晰度过高、设备带不动 | 降低清晰度或音频码率，限制帧率 |
| 文字变方块、布局错乱 | UI 缩放与主题 | 缩放比例与屏幕不匹配 | 调整 UI 缩放，切换主题 |
| 手柄按键不对 | 按键映射设置 | 键位布局与手柄不符 | 更换按键映射，开启 ABXY 交换 |
| 手柄无震动 | 震动开关 | 开关未开、驱动问题 | 开启手柄震动并实测 |
| 无法退出应用 | 应用内退出入口 | 确认对话框未触发 | 用系统任务强制结束 |
先检查环境和基础配置：版本、安装文件、配置目录、网络
多数异常都源于同一批根因，建议按顺序过一遍：
- 平台与版本：先确认下载的安装包与设备一致。PC 要区分 Windows、macOS、Linux；Switch 为 nro 文件，PS Vita 为 vpk，PS4 为 pkg。
- 安装文件：Switch 的 nro 应放在内存卡 switch 目录下，再通过 hbmenu 启动；PS4、PSVita 用系统安装器直接安装；PC 用安装包或系统自带软件商店安装。
- 配置目录：设置页面里有按钮可以直接打开配置目录，wiliwili_config.json 主配置文件就在这里，保存着登录状态、网络代理、播放偏好等。
- 网络连通性：先确认能正常打开其他网站或应用；系统时间错误、DNS 异常或特殊代理，都会导致请求失败。
💡 Switch 用户请额外确认：系统固件与大气层已更新到最新，内存卡为 FAT32 格式，这是正常启动的前提。
启动失败与初始化异常：处理启动报错和配置恢复
启动报错与初始化失败
现象：启动时提示 Unable to init application（无法初始化应用），进不了主界面。
优先检查：安装包与平台是否匹配、配置目录文件是否完整。
处理：
- 重新下载对应平台的安装包并重装，确保文件完整。
- 仍然失败时，进入设置里的检查更新入口，升级到最新版本再试。
- 之前放过自定义主题、自定义字体的，可先把配置目录里相关文件移除再启动。
验证：能正常进入首页，且首页推荐卡片正常加载。
Switch 启动后长时间黑屏
现象：从主界面启动应用后，屏幕长时间停留在黑屏，无法进入。
优先检查：内存卡上的配置目录和内存卡格式。
处理：尝试删除内存卡中的 config/wiliwili 目录后重新进入；若仍黑屏，检查内存卡是否为 FAT32、系统固件是否为最新。
验证：再次启动，能在正常开机时间内进入主界面。
连接、加载与播放异常：处理网络、缓冲与编码问题
首页与搜索结果加载不出来
现象：首页或搜索页卡片一直空白、封面图片加载失败。
优先检查：网络本身 → DNS → 代理。
处理：
- 确认其他网页可正常打开后，使用设置/实用工具里的网络诊断功能，查看与 B 站接口的连通情况。
- 诊断项有异常时，尝试更换公共 DNS，或关闭网络代理后重新测试。
验证：返回首页刷新一次，内容列表与封面图正常显示。
直播弹幕掉线
现象：直播画面正常但弹幕完全不动，日志中出现“无法创建 WebSocket 连接”的提示。
优先检查：直播弹幕依赖长连接，对网络环境和代理最敏感。
处理：关闭代理、有线与 Wi-Fi 之间切换一次，然后重新进入直播间。
验证：进入一个活跃直播间，30 秒内弹幕能持续滚动即恢复。
视频无法播放或加载失败
现象：进入播放页后一直转圈，或提示图片、资源加载失败。
优先检查：是单个视频出问题，还是所有视频都出问题。
处理：
- 只有单个视频异常：多为资源暂不可用，刷新页面或换一档清晰度再试。
- 所有视频都异常：在设置中调整视频编码与视频格式选项，换一组组合测试。
- 低性能设备注意各平台解码上限：PS4 仅支持软解，播放 4K 高帧率需开启低画质解码；Switch OpenGL 版最高支持 4K30。
验证：修改后重启应用，重新进入播放页确认视频可正常出声出画面。
播放卡顿与缓冲
现象：播放中反复缓冲、画面掉帧。
优先检查：当前视频清晰度、音频码率与设备负载。
处理：
- 先降低视频清晰度与音频质量，减少带宽占用。
- 设备性能偏弱时，可在设置中限制帧率，并关闭不必要的后台程序。
- 同清晰度下仍卡顿，尝试更换视频编码组合，或改用对设备更友好的播放模式。
验证：重进同一条视频，缓冲次数明显减少、播放画面稳定。
显示、字体、布局与手柄输入：修复界面和按键异常
字体异常与文字方块
现象：部分字符显示为方块，或表情、弹幕字体显示错乱。
优先检查：是否在配置目录放置过自定义字体文件。
处理：
- 可从设置中打开字体教程，查看字体文件的正确放置方式。
- 若自定义字体导致异常，把配置目录中对应的字体文件移除，恢复内置字体。
验证：重启应用，确认中文、英文、表情均正常显示。
界面布局错乱
现象：组件互相遮挡、被裁切，或整体字号过大过小。
优先检查：UI 缩放与主题设置。
处理：在设置中把 UI 缩放调整为与屏幕分辨率匹配的比例（提供 544p、720p、900p、1080p 等档位）；也可切换深浅主题，排除主题相关文件带来的显示问题。
验证：切换后依次浏览首页、播放页、设置页，确认布局恢复正常。
手柄无响应或按键不对
现象：手柄连上后无反应，或界面按键提示与实际功能不符。
优先检查：物理连接 → 按键映射 → ABXY 布局。
处理：
- 重新插拔或重连手柄，确认系统已识别。
- 在设置中把按键映射切换为与手柄匹配的方案（Xbox、PS、键盘风格等）。
- 觉得 A/B/X/Y 位置别扭时，开启 ABXY 交换。
验证：界面按键提示与实际操作一致，完整走一遍“搜索 → 播放 → 返回”流程无误。
手柄无震动
现象：支持震动的手柄完全没有反馈。
优先检查：设置中的手柄震动开关。
处理：开启手柄震动选项；若仍无震动，可能是手柄本身不支持或驱动异常。也可以借助设置里的震动测试入口触发一次震动来验证。
验证：触发应有震动反馈的操作（如提示弹窗），手柄能正常响应。
闪退、退出、检查更新与求助
应用闪退
现象：使用中途应用自行退出，常发生在某一固定页面。
处理：
- 先用设置中的检查更新功能升级版本，获取最新修复。
- 仍闪退则重新安装；Switch 用户可顺便删除内存卡配置目录再试。
- 记录闪退发生在哪个页面、执行什么操作后出现，便于判断是否特定页面问题。
验证：连续使用 30 分钟以上不再异常退出。
无法退出
现象：应用内退出入口没有反应。
处理：设置页面提供退出按钮，按下会弹出确认对话框；若该路径失效，直接用系统任务管理强制结束程序。
验证：退出后重新进入，确认之前的设置仍生效。
求助前准备
按以上步骤仍无法解决时，再到官方文档或社区提问，建议附上：
- 网络类问题：网络诊断截图（设置/实用工具/网络诊断）。
- 完整描述：在哪个页面、执行什么操作、错误提示原文。
- Switch 用户：大气层与系统固件版本、内存卡格式。
也可以查阅项目官方文档与使用说明，确认是否已有已知问题的记录。
【免费下载链接】wiliwili第三方B站客户端，目前可以运行在PC全平台、PSVita、PS4 、Xbox 和 Nintendo Switch上项目地址: https://gitcode.com/GitHub_Trending/wi/wiliwili
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
