10-09-实战-常见问题与解决方案

实战-常见问题与解决方案

篇章:10-实战篇-从零搭建
状态:已完成
阅读时间:约 25 分钟


一、引言

1.1 本章在系列中的定位

本章是 YooAsset 实战的"避坑指南"。汇集了 YooAsset 使用过程中的高频问题和最佳解决方案,帮助你快速定位和解决生产中遇到的实际问题。

1.2 本章要解决的核心问题

  • YooAsset 启动失败的常见原因
  • 资源加载失败的排查步骤
  • 热更新出问题的处理流程
  • 性能问题的快速诊断

1.3 阅读前置要求

  • 完成 10-01 到 10-08
  • 有过 YooAsset 实际使用经验

二、启动阶段问题

2.1 YooAsset 初始化失败

症状

YooAssets.InitializeAsync() 返回 Failed
Error: ...

排查步骤

步骤 1:检查 PlayMode

// 确保在 Editor 中设置了正确的 PlayMode
// YooAsset → PlayMode → EditorPlayMode 或 HostPlayMode

步骤 2:检查 StreamingAssets

// StreamingAssets/yooasset/ 目录下是否有:
// - PackageManifest_*.bytes
// - PackageManifest_*.hash
// - bundles/

步骤 3:检查 Package 配置

// PackageSettings 中的 PackageName 是否与代码一致
var packageName = "DefaultPackage";  // 必须匹配

步骤 4:检查日志

[RuntimeInitializeOnLoadMethod]
public static void EnableVerboseLog()
{
    YooAssetSettings.VerboseLog = true;
}

解决方案

原因 解决方案
PlayMode 设置错误 重新设置 PlayMode
StreamingAssets 缺失 重新构建并拷贝
Package 名不匹配 修改 PackageSettings
编辑器模式与运行时冲突 切换到合适的 PlayMode

2.2 启动黑屏

症状

游戏启动后一直黑屏,Loading 界面不出现。

原因

启动 UI 资源没放在首包中。

解决方案

步骤 1:检查启动资源

// 启动必需的资产
[StartupPack]
Filter: "Assets/Startup/**/*"
PackTo: InstallPackage

步骤 2:分阶段日志

public class StartupLogger
{
    public static async Task<bool> StartupWithLogs()
    {
        Debug.Log("[1/6] 启动");
        Debug.Log("[2/6] 初始化 YooAsset");
        await InitYooAsset();
        Debug.Log("[3/6] 检查版本");
        await CheckVersion();
        Debug.Log("[4/6] 下载资源");
        await Download();
        Debug.Log("[5/6] 加载主场景");
        await LoadMainScene();
        Debug.Log("[6/6] 完成");
        return true;
    }
}

步骤 3:添加超时保护

public async Task<bool> StartupWithTimeout()
{
    var task = StartupWithLogs();
    var timeout = Task.Delay(TimeSpan.FromSeconds(30));
    var completed = await Task.WhenAny(task, timeout);
    
    if (completed == timeout)
    {
        Debug.LogError("[Startup] 超时!");
        return false;
    }
    
    return await task;
}

2.3 启动闪退

症状

游戏启动后立即闪退。

原因

  • 缺少关键脚本引用
  • AOT 元数据缺失(iOS)
  • 资源依赖循环

解决方案

// 1. 启用详细日志
Debug.unityLogger.logEnabled = true;
Application.SetStackTraceLogType(LogType.Exception, StackTraceLogType.ScriptOnly);

// 2. 全局异常捕获
Application.logMessageReceived += (msg, stack, type) =>
{
    if (type == LogType.Exception)
    {
        // 上报到服务器
    }
};

// 3. iOS 元数据补充
#if UNITY_IOS
public static async Task LoadAOTMetadata()
{
    var aotDlls = new[] { "mscorlib", "System", "System.Core" };
    foreach (var name in aotDlls)
    {
        var op = YooAssets.GetRawFileAsync($"AOT/{name}.dll.bytes");
        await op.Task;
        HybridCLRHelper.LoadMetadataForAOTAssembly(op.Result);
    }
}
#endif

三、加载阶段问题

3.1 资源找不到

症状

LoadAssetAsync("ui_icon_home") 返回 Failed
Error: Asset not found: ui_icon_home

排查步骤

步骤 1:检查 Address

// Address 是否与构建时一致
// 在 Editor 中打开 AddressableAssetSetting → Search → 输入

步骤 2:检查是否被收集

// YooAsset → Collect Asset
// 查看是否被任何 Collector 收集

步骤 3:检查 Filter 规则

// Collector 的 SearchPattern 是否覆盖了该资源
SearchPattern: "Assets/Art/UI/**/*.png"
ExcludePatterns: ["**/Editor/**"]

步骤 4:检查 PackRule

// 确保该资源被打到 Bundle 中
// BuildReport.html 中搜索资源名

解决方案

public class AssetNotFoundHandler
{
    public async Task<T> LoadWithFallback<T>(string location) where T : Object
    {
        var op = YooAssets.LoadAssetAsync<T>(location);
        await op.Task;
        
        if (op.Status != EOperationStatus.Succeed)
        {
            Debug.LogWarning($"[AssetNotFound] {location}");
            
            // 1. 尝试备用 Location
            var fallback = GetFallbackLocation(location);
            if (fallback != null)
            {
                return await LoadWithFallback<T>(fallback);
            }
            
            // 2. 返回默认资源
            return LoadDefault<T>();
        }
        
        return op.Result;
    }
}

3.2 Bundle 加载失败

症状

加载某个资源时,连带 Bundle 失败。

排查步骤

public class BundleFailureDetector
{
    public async Task<T> Diagnose<T>(string location) where T : Object
    {
        var op = YooAssets.LoadAssetAsync<T>(location);
        await op.Task;
        
        if (op.Status == EOperationStatus.Failed)
        {
            Debug.LogError($"[Bundle Failure] {location}");
            Debug.LogError($"  Error: {op.Error}");
            Debug.LogError($"  Bundle: {op.BundleName}");
            Debug.LogError($"  Status: {op.Status}");
            
            // 列出可能原因
            DiagnosePossibleReasons(op);
        }
        
        return op.Status == EOperationStatus.Succeed ? op.Result : null;
    }
    
    void DiagnosePossibleReasons(AsyncOperationBase op)
    {
        if (op.Error.Contains("not found"))
        {
            Debug.LogError("  → 资源可能未被打包");
        }
        else if (op.Error.Contains("hash"))
        {
            Debug.LogError("  → Hash 校验失败,文件损坏");
        }
        else if (op.Error.Contains("network"))
        {
            Debug.LogError("  → 网络错误");
        }
        else if (op.Error.Contains("timeout"))
        {
            Debug.LogError("  → 加载超时");
        }
    }
}

3.3 场景加载卡住

症状

LoadSceneAsync 一直不完成。

排查

public class SceneLoadDebugger
{
    public async Task LoadSceneWithDebug(string sceneName)
    {
        var sw = Stopwatch.StartNew();
        var op = YooAssets.LoadSceneAsync(sceneName);
        
        while (!op.IsDone)
        {
            if (sw.Elapsed.TotalSeconds > 30)
            {
                Debug.LogError($"[SceneLoad] 超时!进度: {op.Progress}");
                Debug.LogError($"  IsDone: {op.IsDone}");
                Debug.LogError($"  Bundle: {op.BundleName}");
                break;
            }
            
            Debug.Log($"[SceneLoad] 进度: {op.Progress:P}");
            await Task.Yield();
        }
        
        Debug.Log($"[SceneLoad] 完成: {sw.Elapsed.TotalSeconds}秒");
    }
}

解决方案

// 1. 异步场景加载 + 进度
public async Task LoadSceneWithProgress(string sceneName, IProgress<float> progress)
{
    var op = YooAssets.LoadSceneAsync(sceneName);
    
    while (!op.IsDone)
    {
        progress?.Report(op.Progress);
        await Task.Yield();
    }
}

// 2. 场景加载 + Loading 界面
public async Task LoadSceneWithLoadingUI(string sceneName)
{
    loadingUI.SetActive(true);
    await LoadSceneWithProgress(sceneName, loadingUI.UpdateProgress);
    loadingUI.SetActive(false);
}

四、热更新问题

4.1 下载卡 99%

症状

下载进度卡在 99% 不动。

原因

  • 某个大文件下载失败
  • Hash 校验不通过
  • 网络超时

解决方案

public class DownloadHangFixer
{
    public async Task<bool> DownloadWithMonitoring()
    {
        var lastProgress = 0f;
        var lastUpdateTime = DateTime.Now;
        
        var downloadOp = YooAssets.DownloadUpdateAsync();
        
        while (!downloadOp.IsDone)
        {
            // 进度卡住检测
            if (Math.Abs(downloadOp.Progress - lastProgress) < 0.001f)
            {
                if (DateTime.Now - lastUpdateTime > TimeSpan.FromSeconds(30))
                {
                    Debug.LogError("[Download] 30 秒无进度,重试");
                    YooAssets.ClearCache();
                    return false;
                }
            }
            else
            {
                lastProgress = downloadOp.Progress;
                lastUpdateTime = DateTime.Now;
            }
            
            await Task.Delay(1000);
        }
        
        return downloadOp.Status == EOperationStatus.Succeed;
    }
}

4.2 Hash 校验失败

症状

下载完成后提示"Hash 校验失败"。

原因

  • 网络传输错误
  • CDN 缓存了错误文件
  • 源站文件被修改

解决方案

public class HashFailureHandler
{
    public async Task<bool> HandleHashFailure(string bundleName)
    {
        Debug.LogWarning($"[HashFailure] {bundleName}");
        
        // 1. 删除损坏文件
        var bundlePath = YooAssets.GetBundlePath(bundleName);
        if (File.Exists(bundlePath))
            File.Delete(bundlePath);
        
        // 2. 重新下载
        return await RetryDownload(bundleName);
    }
    
    async Task<bool> RetryDownload(string bundleName)
    {
        var op = YooAssets.DownloadUpdateAsync();
        await op.Task;
        return op.Status == EOperationStatus.Succeed;
    }
}

4.3 CDN 不可达

症状

所有 CDN 资源都加载失败。

排查

public class CDNHealthChecker
{
    public async Task<CDNStatus> CheckCDN(string url)
    {
        try
        {
            var op = YooAssets.GetRawFileAsync(url);
            await op.Task;
            return CDNStatus.Healthy;
        }
        catch
        {
            return CDNStatus.Unhealthy;
        }
    }
    
    public async Task<string> GetHealthyCDN()
    {
        var cdns = new[] { 
            "https://cdn1.example.com", 
            "https://cdn2.example.com" 
        };
        
        foreach (var cdn in cdns)
        {
            if (await CheckCDN(cdn) == CDNStatus.Healthy)
                return cdn;
        }
        
        return null;
    }
}

解决方案

public class CDNFailover
{
    public async Task<bool> DownloadWithFailover(string path)
    {
        var primaryCDN = "https://cdn1.example.com";
        var backupCDN = "https://cdn2.example.com";
        
        // 1. 尝试主 CDN
        if (await TryCDN(primaryCDN, path))
            return true;
        
        // 2. 切换备用
        if (await TryCDN(backupCDN, path))
            return true;
        
        return false;
    }
}

五、性能问题

5.1 加载慢

症状 原因 解决方案
单个资源加载慢 Bundle 太大 拆分 Bundle
切场景卡顿 依赖链过深 异步分层加载
启动慢 启动资源太多 优化首包
内存峰值高 并发加载过多 限制并发数

5.2 内存泄漏

排查步骤

public class MemoryLeakDetector
{
    public void Detect()
    {
        // 1. 检查引用计数
        var refCountInfos = YooAssets.GetRefCountInfos();
        foreach (var info in refCountInfos)
        {
            if (info.RefCount > 0 && !IsInUse(info.Location))
            {
                Debug.LogWarning($"[PossibleLeak] {info.Location}, RefCount={info.RefCount}");
            }
        }
        
        // 2. 检查 Bundle 数量
        var bundleCount = YooAssets.GetLoadedBundleCount();
        Debug.Log($"[Memory] Loaded Bundles: {bundleCount}");
        
        // 3. 检查缓存大小
        var cacheSize = YooAssets.GetCacheSize();
        Debug.Log($"[Memory] Cache Size: {cacheSize / 1024 / 1024}MB");
    }
    
    bool IsInUse(string location)
    {
        // 业务层判断:是否在场景中使用
        return false;
    }
}

解决方案

public class LeakFixer
{
    public void Fix()
    {
        // 1. 释放未使用资源
        YooAssets.ReleaseAllUnused();
        
        // 2. 卸载未使用 Asset
        Resources.UnloadUnusedAssets();
        
        // 3. 强制 GC
        GC.Collect();
        GC.WaitForPendingFinalizers();
        GC.Collect();
    }
}

5.3 卡顿

排查

public class StuckDetector
{
    private float _lastFrameTime;
    
    void Update()
    {
        var delta = Time.unscaledDeltaTime;
        
        if (delta > 0.1f)  // 100ms 卡顿
        {
            Debug.LogWarning($"[Stuck] Frame time: {delta * 1000:F0}ms");
            // 输出当前堆栈
        }
    }
}

六、构建问题

6.1 构建失败

常见错误

错误 原因 解决
资源找不到 路径错误 检查 SearchPattern
循环依赖 A→B→A 抽离共享包
Bundle 名重复 命名冲突 调整命名
类型不匹配 资源类型错误 检查导入器

6.2 构建产物不对

排查

public class BuildOutputChecker
{
    public void Check(string outputPath)
    {
        // 1. 检查 Manifest
        var manifestPath = $"{outputPath}/PackageManifest_*.bytes";
        var manifests = Directory.GetFiles(outputPath, "PackageManifest_*.bytes");
        if (manifests.Length == 0)
        {
            Debug.LogError("[Build] Manifest 缺失!");
        }
        
        // 2. 检查 Bundle
        var bundles = Directory.GetFiles($"{outputPath}/bundles", "bundle_*");
        if (bundles.Length == 0)
        {
            Debug.LogError("[Build] 无 Bundle 输出!");
        }
        
        // 3. 检查文件大小
        foreach (var bundle in bundles)
        {
            var size = new FileInfo(bundle).Length;
            if (size == 0)
            {
                Debug.LogError($"[Build] {bundle} 为空!");
            }
        }
    }
}

七、跨平台问题

7.1 iOS 平台问题

AOT 元数据缺失

症状:iOS 闪退,Android 正常。

解决:补充 AOT 元数据(参考 09-01)。

文件路径

// iOS 文件路径需特殊处理
public static string GetiOSPath(string relativePath)
{
#if UNITY_IOS
    return Path.Combine(Application.persistentDataPath, relativePath);
#else
    return relativePath;
#endif
}

7.2 Android 平台问题

文件权限

// Android 6.0+ 需要动态权限
public async Task RequestStoragePermission()
{
#if UNITY_ANDROID
    if (!Permission.HasUserAuthorizedPermission(Permission.ExternalStorageWrite))
    {
        Permission.RequestUserPermission(Permission.ExternalStorageWrite);
    }
#endif
}

7.3 小游戏平台问题

微信小游戏

// 微信小游戏的主包限制 4MB
// 必须严格控制首包大小

WebGL

// WebGL 不支持多线程,下载并发需限制
public class WebGLDownloader
{
#if UNITY_WEBGL
    public int MaxConcurrent = 3;  // WebGL 推荐 3 个并发
#else
    public int MaxConcurrent = 10;
#endif
}

八、并发与竞态

8.1 重复加载

症状:同一个资源被多个协程同时加载。

解决:

public class SingleFlightLoader
{
    private readonly Dictionary<string, Task<UnityEngine.Object>> _inflight = new();
    
    public async Task<T> Load<T>(string location) where T : Object
    {
        if (_inflight.TryGetValue(location, out var existing))
            return await existing as T;
        
        var task = LoadInternal<T>(location);
        _inflight[location] = task;
        
        try
        {
            return await task as T;
        }
        finally
        {
            _inflight.Remove(location);
        }
    }
    
    async Task<UnityEngine.Object> LoadInternal<T>(string location) where T : Object
    {
        var op = YooAssets.LoadAssetAsync<T>(location);
        await op.Task;
        return op.Result;
    }
}

8.2 切场景的竞态

症状:切场景时正在下载的资源需要取消。

解决:

public class SceneTransitionWithCleanup
{
    private CancellationTokenSource _cts;
    
    public async Task TransitionToScene(string sceneName)
    {
        // 1. 取消当前场景的下载
        _cts?.Cancel();
        _cts = new CancellationTokenSource();
        
        // 2. 加载新场景
        var op = YooAssets.LoadSceneAsync(sceneName);
        
        // 3. 监听取消
        _cts.Token.Register(() => op.Cancel());
        
        await op.Task;
    }
}

九、内存相关问题

9.1 iOS 内存压力

// iOS 内存压力大时主动释放
public class iOSMemoryManager
{
    void OnApplicationPause(bool pause)
    {
        if (pause)
        {
            // 切后台,主动释放
            YooAssets.ReleaseAllUnused();
            Resources.UnloadUnusedAssets();
            GC.Collect();
        }
    }
}

9.2 低端机适配

public class LowEndDeviceAdaptor
{
    public void Adapt()
    {
        var systemMemory = SystemInfo.systemMemorySize;  // MB
        
        if (systemMemory < 2048)  // 小于 2GB
        {
            // 降低资源质量
            YooAssetSettings.MaxConcurrentDownloads = 3;
            YooAssetSettings.EnablePreload = false;
            
            // 主动降低加载频率
        }
    }
}

十、调试工具与方法

10.1 自检清单

每次发版前的自检:

□ 所有资源都能正常加载
□ 热更新流程跑通
□ CDN 可达性验证
□ 首包大小符合预期
□ 启动时间 < 30 秒
□ 内存峰值 < 1.5GB
□ 关键场景加载 < 5 秒
□ 灰度用户反馈
□ 监控告警配置
□ 回滚方案验证

10.2 快速诊断脚本

public class QuickDiagnose
{
    [MenuItem("YooAsset/Quick Diagnose")]
    public static void Run()
    {
        // 1. 检查 Package 配置
        var package = YooAssets.GetCurrentPackage();
        Debug.Log($"[Diagnose] Package: {package?.Name ?? "null"}");
        
        // 2. 检查清单
        var manifest = YooAssets.GetPackageManifest();
        Debug.Log($"[Diagnose] Manifest version: {manifest?.PackageVersion ?? "null"}");
        
        // 3. 检查缓存
        var cacheSize = YooAssets.GetCacheSize();
        Debug.Log($"[Diagnose] Cache size: {cacheSize / 1024 / 1024}MB");
        
        // 4. 检查网络
        Debug.Log($"[Diagnose] Network: {Application.internetReachability}");
        
        Debug.Log("[Diagnose] 完成");
    }
}

10.3 监控告警

指标 告警阈值
启动失败率 > 1%
热更新失败率 > 0.5%
平均加载时间 > 5s
内存峰值 > 1.2GB
CDN 5xx > 0.1%
玩家反馈 异常激增

十一、总结

11.1 本章要点回顾

  • 启动问题:PlayMode、首包、配置
  • 加载问题:Address、Bundle、场景
  • 热更新问题:下载卡、Hash 失败、CDN 不可达
  • 性能问题:加载慢、内存泄漏、卡顿
  • 构建问题:依赖、资源、平台
  • 跨平台问题:iOS 元数据、Android 权限、小游戏

11.2 与前后章节的关联

  • 前章:10-08 介绍了调试与性能分析
  • 本章:聚焦常见问题与解决方案
  • 后章:10-10 将介绍小游戏首包规划

11.3 实践建议

  1. 错误处理必做:每个加载都要有 fallback
  2. 监控先行:先有监控,再上线
  3. 诊断工具自建:根据项目特点定制
  4. 常见问题文档化:积累团队知识库
  5. 代码审查:预防胜于治疗

上一篇:调试与性能分析
下一篇:小游戏首包资源规划与策略

posted @ 2026-11-20 09:56  SmalBox  阅读(10)  评论(0)    收藏  举报