450 lines
17 KiB
Markdown
450 lines
17 KiB
Markdown
# 56 · 崩溃恢复与错误处理系统（Crash Recovery & Error Handling）
|
||
|
||
> **命名空间** `BaseGames.Reliability`
|
||
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)
|
||
> **依赖** `BaseGames.World`（SaveManager）· `BaseGames.Platform`（IPlatformService）
|
||
> **关联** 31_SaveDataSchema_Unified · 46_PlatformIntegration · 55_AnalyticsTelemetrySystem
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [系统总览](#1-系统总览)
|
||
2. [紧急自动存档机制](#2-紧急自动存档机制)
|
||
3. [存档写入失败处理](#3-存档写入失败处理)
|
||
4. [云存档冲突解决](#4-云存档冲突解决)
|
||
5. [崩溃报告器集成](#5-崩溃报告器集成)
|
||
6. [启动时数据完整性检查](#6-启动时数据完整性检查)
|
||
7. [错误 UI 规范](#7-错误-ui-规范)
|
||
8. [错误等级分类](#8-错误等级分类)
|
||
9. [SaveManager 防御性编程规范](#9-savemanager-防御性编程规范)
|
||
10. [编辑器友好设计](#10-编辑器友好设计)
|
||
|
||
---
|
||
|
||
## 1. 系统总览
|
||
|
||
```
|
||
崩溃恢复系统职责:
|
||
├─ EmergencySaveService → 应用暂停/退出前触发紧急存档
|
||
├─ SaveWriteErrorHandler → 处理磁盘满、权限拒绝等写入失败场景
|
||
├─ CloudConflictResolver → 云存档与本地存档版本冲突时的 UI 决策流
|
||
├─ CrashReporter → 捕获未处理异常，发送崩溃报告（可选联网）
|
||
└─ SaveIntegrityChecker → 启动时验证存档文件完整性，自动修复或降级
|
||
```
|
||
|
||
**核心原则**：玩家的进度安全**高于**一切其他系统优先级。每个错误路径都必须有明确的恢复策略，绝不因技术失败静默丢失玩家进度。
|
||
|
||
---
|
||
|
||
## 2. 紧急自动存档机制
|
||
|
||
### 2.1 触发时机
|
||
|
||
```csharp
|
||
namespace BaseGames.Reliability
|
||
{
|
||
/// <summary>
|
||
/// 挂载在 Persistent Scene，监听应用生命周期事件，触发紧急存档
|
||
/// </summary>
|
||
public class EmergencySaveService : MonoBehaviour
|
||
{
|
||
[SerializeField] SaveManager _saveManager;
|
||
[SerializeField] float _autoSaveIntervalSeconds = 300f; // 5 分钟定时自动存
|
||
[SerializeField] bool _saveOnPause = true; // 平台切换时存档
|
||
|
||
float _lastAutoSaveTime;
|
||
|
||
void Update()
|
||
{
|
||
// 定时自动存档（普通游玩中，每5分钟静默存档到"自动存档槽"）
|
||
if (Time.realtimeSinceStartup - _lastAutoSaveTime >= _autoSaveIntervalSeconds)
|
||
{
|
||
TriggerEmergencySave("AutoSave_Timer");
|
||
_lastAutoSaveTime = Time.realtimeSinceStartup;
|
||
}
|
||
}
|
||
|
||
void OnApplicationPause(bool paused)
|
||
{
|
||
if (paused && _saveOnPause)
|
||
TriggerEmergencySave("AutoSave_Pause");
|
||
}
|
||
|
||
void OnApplicationQuit()
|
||
{
|
||
// OnApplicationQuit 是同步的，使用同步存档路径
|
||
_saveManager.SaveEmergencySync("AutoSave_Quit");
|
||
}
|
||
|
||
private void TriggerEmergencySave(string reason)
|
||
{
|
||
// 仅当玩家处于"正常游玩"状态时才自动存档
|
||
// （不在主菜单、不在过场动画、不在 Boss 战高潮）
|
||
if (!_saveManager.IsInSaveableState) return;
|
||
|
||
_ = _saveManager.SaveEmergencyAsync(reason);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 自动存档槽设计
|
||
|
||
| 槽位 | 触发条件 | 保留策略 |
|
||
|------|---------|---------|
|
||
| `AutoSave_01` | 定时（5分钟）/ 暂停 | 轮转：始终覆盖最旧的自动存档 |
|
||
| `AutoSave_02` | 同上（交替覆盖）| 轮转 |
|
||
| `AutoSave_Exit` | 退出游戏 | 始终是最后一次退出前的状态 |
|
||
| `Manual_01~03` | 玩家手动存档 | 玩家控制，不被自动存档覆盖 |
|
||
|
||
**自动存档不覆盖手动存档槽**——用于防止玩家手动存错位置后无法回退。
|
||
|
||
### 2.3 自动存档的 UI 呈现
|
||
|
||
- 自动存档时，屏幕右下角显示 `SaveIndicator`（参见 10_UISystem.md §17），持续 1.5s
|
||
- 不打断游戏（不弹对话框，不暂停）
|
||
- 失败时（见 §3）才显示警告
|
||
|
||
---
|
||
|
||
## 3. 存档写入失败处理
|
||
|
||
### 3.1 失败原因矩阵
|
||
|
||
| 原因 | 检测方式 | 处理策略 |
|
||
|------|---------|---------|
|
||
| 磁盘空间不足 | `IOException: No space left` | 弹出警告 UI + 引导玩家清理磁盘 |
|
||
| 写入权限拒绝 | `UnauthorizedAccessException` | 提示权限问题 + 尝试写入备用路径 |
|
||
| 路径不存在 | `DirectoryNotFoundException` | 自动创建目录，重试一次 |
|
||
| 文件被占用 | `IOException: File in use` | 等待 500ms 后重试，最多 3 次 |
|
||
| JSON 序列化失败 | `JsonException` | 记录错误日志，保留上一个有效存档 |
|
||
|
||
### 3.2 SaveWriteErrorHandler
|
||
|
||
```csharp
|
||
namespace BaseGames.Reliability
|
||
{
|
||
public static class SaveWriteErrorHandler
|
||
{
|
||
/// <summary>
|
||
/// 包装存档写入，统一处理所有失败场景
|
||
/// </summary>
|
||
public static async UniTask<SaveWriteResult> SafeWrite(
|
||
string path, byte[] data, CancellationToken ct = default)
|
||
{
|
||
// 确保目录存在
|
||
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
|
||
|
||
// 先写临时文件，写成功后原子替换（防止写到一半崩溃导致存档损坏）
|
||
string tempPath = path + ".tmp";
|
||
int retries = 0;
|
||
|
||
while (retries < 3)
|
||
{
|
||
try
|
||
{
|
||
await File.WriteAllBytesAsync(tempPath, data, ct);
|
||
File.Replace(tempPath, path, path + ".bak"); // 同时保留备份
|
||
return SaveWriteResult.Success;
|
||
}
|
||
catch (IOException ex) when (ex.Message.Contains("No space"))
|
||
{
|
||
return SaveWriteResult.DiskFull;
|
||
}
|
||
catch (UnauthorizedAccessException)
|
||
{
|
||
return SaveWriteResult.PermissionDenied;
|
||
}
|
||
catch (IOException)
|
||
{
|
||
retries++;
|
||
if (retries >= 3) return SaveWriteResult.FileInUse;
|
||
await UniTask.Delay(500, cancellationToken: ct);
|
||
}
|
||
}
|
||
return SaveWriteResult.Unknown;
|
||
}
|
||
}
|
||
|
||
public enum SaveWriteResult { Success, DiskFull, PermissionDenied, FileInUse, Unknown }
|
||
}
|
||
```
|
||
|
||
### 3.3 写入失败 UI（SaveErrorPanel）
|
||
|
||
当任何存档写入返回非 `Success` 时，弹出 `SaveErrorPanel`：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ ⚠ 存档失败 │
|
||
│ │
|
||
│ 无法保存进度：磁盘空间不足。 │
|
||
│ 请清理磁盘后重试，否则本次进度可能丢失。 │
|
||
│ │
|
||
│ 当前可用空间：约 128 MB │
|
||
│ 建议至少留有：200 MB 空余 │
|
||
│ │
|
||
│ [ 打开文件管理器 ] [ 重试存档 ] [ 忽略 ] │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- "打开文件管理器"：`System.Diagnostics.Process.Start("explorer.exe", folderPath)` 仅 PC 平台
|
||
- "重试存档"：立即重新触发存档流程
|
||
- "忽略"：玩家自担风险，下次存档再次提示
|
||
|
||
---
|
||
|
||
## 4. 云存档冲突解决
|
||
|
||
### 4.1 冲突场景
|
||
|
||
玩家在两台设备上游玩（如 PC + Steam Deck），下线时设备 A 存档比云端新，或云端被设备 B 覆盖。
|
||
|
||
### 4.2 冲突检测
|
||
|
||
```csharp
|
||
public class CloudConflictDetector
|
||
{
|
||
public async UniTask<ConflictInfo?> DetectConflict(
|
||
SaveMeta localMeta, IPlatformService platform)
|
||
{
|
||
var cloudData = await platform.CloudLoadAsync("save_meta.json");
|
||
if (cloudData == null) return null; // 云端无存档，无冲突
|
||
|
||
var cloudMeta = JsonSerializer.Deserialize<SaveMeta>(cloudData);
|
||
|
||
// 比较时间戳（UTC）
|
||
if (cloudMeta.LastSavedUtc > localMeta.LastSavedUtc + TimeSpan.FromSeconds(30))
|
||
{
|
||
// 云端更新（在另一台设备上有游玩进度）
|
||
return new ConflictInfo
|
||
{
|
||
LocalMeta = localMeta,
|
||
CloudMeta = cloudMeta,
|
||
CloudNewer = true
|
||
};
|
||
}
|
||
return null;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 冲突解决 UI（CloudConflictPanel）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 检测到存档冲突 │
|
||
│ │
|
||
│ 发现两份不同的存档，请选择保留哪个版本： │
|
||
│ │
|
||
│ ┌──────────────────────┐ ┌──────────────────────┐ │
|
||
│ │ 本地存档 │ │ 云端存档 │ │
|
||
│ │ 上次保存: 2小时前 │ │ 上次保存: 30分钟前 │ │
|
||
│ │ 区域: 废墟区域 │ │ 区域: 深渊裂隙 │ │
|
||
│ │ 完成度: 52% │ │ 完成度: 61% │ │
|
||
│ │ 游玩时长: 18h 20m │ │ 游玩时长: 21h 05m │ │
|
||
│ └──────────────────────┘ └──────────────────────┘ │
|
||
│ │
|
||
│ [ 使用本地存档 ] [ 使用云端存档（推荐） ] │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- "推荐"标签自动附在时间更新且游玩时长更长的版本上
|
||
- 未选择的版本备份到 `save_slot_X_conflict_backup.json`（不直接删除）
|
||
|
||
---
|
||
|
||
## 5. 崩溃报告器集成
|
||
|
||
### 5.1 未处理异常捕获
|
||
|
||
```csharp
|
||
namespace BaseGames.Reliability
|
||
{
|
||
public class CrashReporter : MonoBehaviour
|
||
{
|
||
[SerializeField] CrashReporterConfigSO _config;
|
||
|
||
void Awake()
|
||
{
|
||
Application.logMessageReceived += OnLogMessage;
|
||
AppDomain.CurrentDomain.UnhandledException += OnUnhandledException;
|
||
}
|
||
|
||
private void OnLogMessage(string condition, string stackTrace, LogType type)
|
||
{
|
||
if (type != LogType.Exception && type != LogType.Error) return;
|
||
if (!_config.enableCrashReporting) return;
|
||
|
||
var report = new CrashReport
|
||
{
|
||
GameVersion = Application.version,
|
||
Platform = Application.platform.ToString(),
|
||
UnityVersion = Application.unityVersion,
|
||
Message = condition,
|
||
StackTrace = stackTrace, // 不包含个人信息
|
||
Timestamp = DateTimeOffset.UtcNow.ToString("O"),
|
||
SceneName = SceneManager.GetActiveScene().name
|
||
};
|
||
|
||
// 写入本地崩溃日志（始终执行）
|
||
WriteCrashLogLocal(report);
|
||
|
||
// 若玩家同意遥测，异步上传（使用遥测系统的上传队列）
|
||
if (PlayerPrefs.GetInt("analytics_consent", 0) == 1)
|
||
_ = UploadCrashReportAsync(report);
|
||
}
|
||
|
||
private void WriteCrashLogLocal(CrashReport report)
|
||
{
|
||
string path = Path.Combine(
|
||
Application.persistentDataPath,
|
||
"Crashes",
|
||
$"crash_{DateTimeOffset.UtcNow:yyyyMMdd_HHmmss}.json");
|
||
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
|
||
File.WriteAllText(path, JsonSerializer.Serialize(report));
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 推荐崩溃报告服务
|
||
|
||
| 服务 | 适用场景 | 定价 |
|
||
|------|---------|------|
|
||
| **Sentry** | 有后端时推荐，免费层够用 | 免费（5K 事件/月）|
|
||
| **Unity Cloud Diagnostics** | Unity 原生，无需额外配置 | 随 Unity 订阅 |
|
||
| **自建日志收集** | 完全隐私控制 | 服务器成本 |
|
||
|
||
集成方式：SDK 的 `Init()` 调用在 `CrashReporter.Awake()` 中执行，且仅当 `analytics_consent == 1` 时。
|
||
|
||
---
|
||
|
||
## 6. 启动时数据完整性检查
|
||
|
||
### 6.1 SaveIntegrityChecker
|
||
|
||
```csharp
|
||
public class SaveIntegrityChecker
|
||
{
|
||
/// <summary>
|
||
/// 游戏启动后，加载存档前执行完整性检查
|
||
/// </summary>
|
||
public static SaveLoadResult CheckAndRepair(string savePath)
|
||
{
|
||
if (!File.Exists(savePath))
|
||
return SaveLoadResult.FileNotFound;
|
||
|
||
var bytes = File.ReadAllBytes(savePath);
|
||
|
||
// 1. Checksum 验证（参见 31_SaveDataSchema §8）
|
||
if (!ChecksumValidator.Verify(bytes))
|
||
{
|
||
// 尝试从备份恢复
|
||
string backupPath = savePath + ".bak";
|
||
if (File.Exists(backupPath))
|
||
{
|
||
File.Copy(backupPath, savePath, overwrite: true);
|
||
return SaveLoadResult.RestoredFromBackup;
|
||
}
|
||
return SaveLoadResult.Corrupted;
|
||
}
|
||
|
||
// 2. JSON Schema 版本检查
|
||
var json = Encoding.UTF8.GetString(bytes);
|
||
var meta = JsonSerializer.Deserialize<SaveVersionMeta>(json);
|
||
if (meta.SchemaVersion < SaveConstants.MinSupportedVersion)
|
||
return SaveLoadResult.TooOld;
|
||
|
||
return SaveLoadResult.OK;
|
||
}
|
||
}
|
||
|
||
public enum SaveLoadResult { OK, FileNotFound, Corrupted, RestoredFromBackup, TooOld }
|
||
```
|
||
|
||
### 6.2 各结果的 UI 处理
|
||
|
||
| 结果 | UI 行为 |
|
||
|------|---------|
|
||
| `OK` | 静默加载，正常进入游戏 |
|
||
| `FileNotFound` | 主菜单存档槽显示"空槽" |
|
||
| `RestoredFromBackup` | 弹出小通知"存档文件已从备份恢复" |
|
||
| `Corrupted` | 弹出警告"存档文件已损坏，无法读取"，提供删除选项 |
|
||
| `TooOld` | "此存档来自旧版本，无法兼容，已归档备份" |
|
||
|
||
---
|
||
|
||
## 7. 错误 UI 规范
|
||
|
||
所有错误 UI 遵循统一的视觉语言（`ErrorPanel` 组件，继承 `UIPanel`）：
|
||
|
||
| 属性 | 规范 |
|
||
|------|------|
|
||
| 图标 | ⚠（黄色）= 警告 / ❌（红色）= 致命错误 |
|
||
| 标题 | 简短，描述发生了什么（"存档失败"，而非"IOException"）|
|
||
| 正文 | 描述原因 + 玩家可做什么（不展示技术栈信息）|
|
||
| 按钮 | 最多3个，优先推荐操作高亮 |
|
||
| 取消方式 | 致命错误不可 Escape 取消，警告可以 |
|
||
| 错误码 | 右下角小字显示（如 `ERR-SAVE-001`），供客服/社区参考，不向普通玩家解释 |
|
||
|
||
---
|
||
|
||
## 8. 错误等级分类
|
||
|
||
| 等级 | 定义 | 示例 | 处理 |
|
||
|------|------|------|------|
|
||
| **INFO** | 非错误，仅记录 | 自动存档完成 | 仅写日志 |
|
||
| **WARNING** | 可继续但需注意 | 备份存档恢复成功 | 屏幕通知 + 日志 |
|
||
| **ERROR** | 功能受损，需用户操作 | 存档写入失败 | 错误 UI + 日志 |
|
||
| **FATAL** | 无法继续游戏 | 存档完全损坏且无备份 | 全屏错误弹窗 + 退出选项 |
|
||
|
||
```csharp
|
||
// 在所有 catch 块中使用统一的错误上报方法，不直接 Debug.LogError
|
||
ErrorReporter.Report(ErrorLevel.ERROR, "ERR-SAVE-001",
|
||
userMessage: "存档失败：磁盘空间不足",
|
||
technicalDetail: ex.ToString(),
|
||
context: savePath);
|
||
```
|
||
|
||
---
|
||
|
||
## 9. SaveManager 防御性编程规范
|
||
|
||
SaveManager 中的所有存档相关代码必须遵守：
|
||
|
||
```csharp
|
||
// ✅ 正确：原子写入，有备份，有错误处理
|
||
var result = await SaveWriteErrorHandler.SafeWrite(savePath, serializedData);
|
||
if (result != SaveWriteResult.Success)
|
||
ErrorReporter.Report(ErrorLevel.ERROR, "ERR-SAVE-001", ...);
|
||
|
||
// ❌ 禁止：直接 File.WriteAllText，无错误处理
|
||
File.WriteAllText(path, json);
|
||
|
||
// ✅ 正确：反序列化加 try-catch，失败时返回新存档（而非 null）
|
||
try {
|
||
return JsonSerializer.Deserialize<SaveData>(json);
|
||
} catch (JsonException) {
|
||
ErrorReporter.Report(ErrorLevel.ERROR, "ERR-SAVE-002", ...);
|
||
return SaveData.CreateDefault();
|
||
}
|
||
|
||
// ❌ 禁止：未处理的反序列化调用
|
||
return JsonSerializer.Deserialize<SaveData>(json);
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 编辑器友好设计
|
||
|
||
- **SaveIntegrityChecker 工具**：EditorWindow 按钮可对当前所有存档文件运行完整性检查，输出 OK/Corrupted/Recoverable 状态
|
||
- **崩溃日志查看器**：EditorWindow 列出 `{persistentDataPath}/Crashes/` 下所有崩溃日志，可查看详细信息和 StackTrace
|
||
- **存档写入模拟**：Inspector 中提供"模拟磁盘满"按钮（Editor 专属），测试错误 UI 流程
|
||
- **云冲突模拟**：调试菜单（42_DebugCheatSystem）中可手动触发云存档冲突 UI
|
||
|
||
---
|
||
|
||
*本文档版本 1.0 · 2026-04 · 关联 31_SaveDataSchema_Unified / 46_PlatformIntegration / 55_AnalyticsTelemetrySystem*
|