企业官网建设流程全解析

Whisky 是一款基于 SwiftUI 构建的现代 macOS 版 Wine 封装器（Wine wrapper），让你直接在 Apple Silicon 上运行 Windows 游戏与程序。而内置的故障排除向导（Troubleshooting Wizard）则是它的"急诊室"：当你遇到游戏崩溃、启动即闪退、画面黑屏、无声、卡顿等问题时，向导会以"检查 → 修复 → 验证"的自动化流程一步步带你定位并修复问题，无需手动翻日志、改注册表。本文将带你完整走查这 8 大症状排查流程。

什么是 Whisky 故障排除向导？

Whisky 的故障排除向导是一个JSON 驱动的自动化诊断状态机。它的运行逻辑可以概括为四个阶段：

1. Checks（检查）：自动读取崩溃日志、图形后端设置、音频设备、Winetricks 组件等，判断问题根源；
2. Fix（修复）：根据检查结果，一键应用修复方案（例如把图形后端切换为 DXVK、安装缺失的 VC++ 组件）；
3. Verify（验证）：让你重新启动程序，确认问题是否解决；
4. Escalate（升级）：若自动修复失败，则提供增强诊断、导出报告等进阶手段。

核心引擎位于 TroubleshootingFlowEngine.swift，它不依赖任何 UI 代码，纯逻辑驱动；每一步检查结果都会显示"证据"（如匹配到的日志模式、当前后端名称），让你清楚知道为什么要这样修。

3 个快速入口：如何启动故障排除向导？

你可以通过以下三个入口启动向导：

比如当 Wine 进程崩溃时，配置页会提示你"分析 Wine 崩溃输出以获取排查建议"，点击后直接进入向导；若 Whisky 在 ProgramView.swift 中检测到失败信号，也会出现 TroubleshootingEntryBanner.swift 定义的可点击横幅，提示你"继续未完成的排查会话"或"有可用的排查指南"。

8 大症状流程全解：一键定位你的问题

打开向导后，首先看到的是 SymptomPickerView.swift 渲染的症状选择网格——8 个分类，每个分类对应一份独立的 JSON 流程定义文件（存放在 flows/ 目录，索引见 index.json）：

除 8 大分类外还有一个低调的"Other"选项，用于其他无法归类的问题。

典型流程深度走查

场景一：游戏启动即崩溃（launch-crash）

这是最常见的场景。流程从crash.log_classify检查开始——自动分析最近一次崩溃日志，识别错误特征（如内存访问违例、GPU 相关错误）：

• 若日志显示图形相关崩溃→ 检查当前图形后端，若不是 DXVK，一键切换（该修复可逆、无需确认）；
• 若日志提示内存访问违例→ 检查 Winetricks 组件（vcrun2019、dotnet48、d3dcompiler_47），缺失则引导安装（此类修复不可逆，向导会先请求你确认）；
• 每一步修复后都会进入verify节点："重启程序试试，修好了吗？" 回答 Yes 即标记为已解决。

场景二：黑屏与图形问题（graphics）

遇到黑屏、闪烁、画面伪影时选择"图形问题"流程。它会依次：

1. 检查图形后端是否为 DXVK（DXVK 兼容性最广）；
2. 分析日志中的 GPU 相关错误模式；
3. 检查 DXVK 异步着色器编译（async shader compilation）是否开启，未开启则自动启用，减少画面卡顿与闪烁。

场景三：无声与爆音（audio）

音频流程依次检查输出设备、Wine 音频驱动注册表配置、DirectSound 缓冲区预设、系统采样率。爆音（crackling）通常意味着缓冲区过小，向导会切换到"稳定音频延迟预设"（更大的 DirectSound 缓冲区）来解决。

场景四：玩着玩着开始卡顿（performance-stability）

性能流程会检查enhanced sync（esync/msync）是否启用——开启后可显著降低 CPU 开销、改善帧节奏；随后还会建议开启 DXVK HUD 监控帧时间。

修复机制：安全、透明、可回退

向导的每个 fix 节点都带有fixPreview（修复预览），会明确展示：

• 改什么：如"Graphics Backend: 当前值 → dxvk"；
• 作用域：改 Bottle 级设置还是单个程序；
• 是否可逆：可逆的修复（如切换后端）自动应用；不可逆的修复（如安装组件）必须经你手动确认。

具体修复动作由 FixApplicator.swift 执行，检查项实现集中在 Checks/ 目录（共 15 个检查：音频、驱动、崩溃日志、后端、DLL、注册表、进程等）。引擎还内置了循环保护——连续自动步骤超过 50 步会强制进入升级流程，避免"死循环"。

修不好怎么办？升级（Escalate）路径

当自动修复穷尽后，向导进入 EscalationView.swift 定义的升级页面，会展示你本次会话的全部修复尝试摘要，并提供四个选项：

1. 📋 以WINEDEBUG 预设重新运行程序，采集增强日志；
2. 📤导出诊断报告（脱敏处理，可安全分享）；
3. ✉️ 生成支持请求草稿；
4. 🔄从之前某一步重试（比如换一个修复方向）。

如果你遇到了更严重的系统级问题（内核恐慌、整机冻结、Whisky 本身崩溃），还可以参考官方维护者指南 docs/StabilityTroubleshooting.md，其中介绍了 Sequoia 兼容模式、关闭 DXR、Kill All Bottles 等快速缓解手段。

💡小技巧：如果所有修复都无效，把程序迁移到一个全新的 Bottle（如上图创建新 Bottle）再按向导流程装一遍依赖，往往能排除环境残留问题。

会话自动保存：中途退出也不怕

向导每一步都会自动保存会话状态（见 TroubleshootingSessionStore.swift）。中途关掉应用没关系——下次打开时，横幅会提示你"继续未完成的排查会话"，由 SessionResumeView.swift 接管。若期间相关设置已变化，向导还会列出变化项供你确认。历史会话可在 TroubleshootingHistoryView.swift 中回看。

常见问题 FAQ

Q：向导会修改我的系统吗？只会修改 Bottle/程序内部设置（如 Wine 注册表、后端选择、esync 开关）或通过 Winetricks 在 Bottle 内安装组件，不会动 macOS 系统文件。且每个修改都有预览，不可逆操作需你手动确认。

Q：向导能修复所有问题吗？不能。它覆盖 8 类高频场景；对系统级故障（内核恐慌、硬件问题）它会引导你导出诊断报告并联系维护者。

Q：崩溃诊断（Diagnostics）和故障排除向导（Troubleshooting）有什么区别？前者（DiagnosticsView.swift）是"只读体检"——分析日志、给出诊断结论；后者是"治疗"——在诊断基础上直接执行修复并验证。两者可无缝衔接：诊断页底部可直接跳入向导。

总结

Whisky 的故障排除向导把过去"翻日志、查文档、盲改配置"的繁琐排查，变成了一条可视化的检查 → 修复 → 验证流水线：8 大症状分类覆盖绝大多数游戏问题，修复前透明预览、修复后可回退，修不好还有升级路径兜底。下次遇到崩溃、黑屏或无声，不妨先打开向导，让它替你完成 90% 的排障工作。