1. 热更新链条上最容易出事的三个环节先说个真实场景。有一次线上版本发完热更包运营那边反馈有大概 3% 的玩家卡在启动资源加载界面日志里全是 AssetBundle 加载超时和 CRC 校验失败。当时第一反应是 CDN 节点出了问题结果查了一圈问题出在本地缓存的 manifest 版本和 CDN 上的清单对不上——一部分玩家上一个版本的热更资源没清理干净把新版本的文件名和 hash 索引全搞乱了。做 Unity AssetBundle 热更新最怕的就是这种看起来是网络问题实际上是本地状态问题的排查。热更新链条本身并不复杂核心就三条线CDN 清单分发远端服务器上存的版本索引、manifest 文件、资源 bundle 文件。这里决定该下载什么、该更新什么。下载与落盘客户端根据清单去拉取资源写入本地缓存目录。这里决定下载的文件对不对、全不全。本地缓存与加载Unity 的 AssetBundle 加载接口从本地文件或缓存系统中读取资源。这里决定加载到的是不是最新版本、有没有被污染。绝大多数热更新安全事故和线上故障都能归到这三个环节中的某一段。排查的时候如果一上来就盯着某一个点猛查很容易漏掉真正的根因。我的习惯是先画一条完整的数据流远程清单 - 版本比对 - 下载队列 - 缓存写入 - 加载验证。每一段都有自己独立的日志和校验点排查时逐个检查比盲目重试高效得多。2. CDN 侧排查从清单文件到 URL 校验2.1 先搞清楚清单文件里存的到底是什么AssetBundle 热更新的前提是有一个清单告诉客户端当前线上有哪些资源、每个资源的文件名、大小、哈希值、依赖关系。这个清单本身就是一个普通的文本或二进制文件常见做法是 JSON 格式里面大致长这样{ version: 1.4.2, bundles: [ { name: ui/mainpanel, md5: 7a3c9f2b1e..., size: 102400, dependencies: [ui/common, shared/textures] } ] }排查 CDN 侧问题的时候第一件事就是把客户端实际拿到的清单内容和 CDN 源站上的清单内容做对比。很多坑都出在客户端拿到的清单不是你以为的那份CDN 边缘节点缓存了旧版本清单TTL 没到新版本发出去之后部分节点还在吐旧数据。清单文件被 CDN 做了压缩处理客户端请求时带了 Accept-Encoding但解析逻辑没做对应解压。回源路径配置错误导致请求打到旧的源站目录。所以热更系统的 CDN 配置里清单文件必须设置为不缓存或者极短 TTL而 bundle 资源文件可以走长效缓存。如果项目用的是阿里云 OSS CDN 或者腾讯云 COS这类对象存储服务基本都支持指定 Cache-Control 头清单文件加no-cache资源文件加长缓存时间。2.2 URL 里的版本号和校验参数别省很多团队图省事下载 URL 直接写死资源名比如https://cdn.example.com/assetbundles/ui/mainpanel。这种方案在排查期最痛苦你没办法让客户端强制拉取某个特定版本的资源一旦 CDN 缓存过期策略出问题客户端拿到的永远是旧文件。我推荐的做法是把版本信息直接编码进 URL 路径或者查询参数https://cdn.example.com/assetbundles/1.4.2/ui/mainpanel https://cdn.example.com/assetbundles/ui/mainpanel?v1.4.2hash7a3c9f2b这样做的核心价值在于版本变了 URL 就变了CDN 的缓存自动失效不需要人为干预。而且 hash 参数可以作为下载完成后校验的一部分URL 里带 hash 还能顺带做 CDN 边缘鉴权。之前我们遇到过一个问题CDN 节点回源异常客户端拿到的 bundle 文件是少数几个节点上的脏数据但因为 URL 里带了预期 hash客户端下载完先比对不一致就直接报错并触发重试而不是把脏资源直接用起来——这一步挽救了那次发布。需要注意URL 带版本号有一个副作用旧版本资源在 CDN 上不会被主动清理久而久之存储量越来越大。解决方式是定期跑一个 CDN 刷新或者目录清理任务但这是运维侧的事不影响客户端逻辑。2.3 清单校验不能只靠依赖 MD5只比对 bundle 文件的 MD5 是不够的。清单本身也必须做签名校验。做法很简单在服务端生成清单时用私钥对清单内容做签名客户端内置公钥加载清单时先验证签名再解析内容。之前见过一个项目资源被人恶意篡改后在各个游戏群传播玩家挂上代理此类网络代理场景且不做展开加载恶意资源导致客户端出现异常弹窗。用户拿到那套资源的第一个入口就是热更清单没有签名校验。所以清单签名不是一个可选项凡是有真实用户的热更新项目这一步必须做。签名算法选 HMAC-SHA256 就好配上每个客户端的随机盐能有效防止请求重放。3. 本地缓存排查目录结构、加载接口与生命周期3.1 先弄清你的缓存是 Caching 系统还是自研目录Unity 的 AssetBundle 缓存有两条路线使用Caching.GetCache/Caching.AddCache管理的 Unity 内置缓存系统。自己在Application.persistentDataPath下面建目录用AssetBundle.LoadFromFile/LoadFromMemory加载。两条路线各有各的坑。用内置缓存系统好处是 Unity 帮你处理了文件命名和索引坏处是排查时你很难直接看到文件。缓存文件散落在系统目录里你没法直观地确认它到底是什么版本。而且 Unity 的 Caching 系统在不同版本之间行为有差异特别是 2019、2020 到 2021 之后的版本Caching.ready状态和同步接口的行为都有变化。自研目录的优点是可排查性强文件结构完全可控缺点是下载、校验、清理全都要自己写。我个人的建议是如果项目团队有排查能力尽量自研缓存目录。不是因为内置系统不好而是因为热更新出问题时一个透明的目录结构能救命。以我们项目为例缓存目录长这样persistentDataPath/AssetBundles/ ├── 1.4.2/ │ ├── manifest.json │ ├── ui_mainpanel │ ├── ui_common │ └── shared_textures ├── 1.4.1/ │ ├── manifest.json │ └── ui_oldpanel └── current_versioncurrent_version是一个文本文件记录当前活跃的版本号加载时先读它再去对应版本目录里找资源。3.2 缓存完整性与残留文件排查本地缓存最常见的安全隐患是文件不完整或者文件被污染。Unity 的LoadFromFile接口对损坏文件的行为是直接返回 null不会给你报具体原因。这时候就需要你有一个校验机制在下载完成后立刻做一次完整性检查而不是等到加载时才发现。我们的做法是三步下载完成后用清单里的 MD5/SHA256 做对比。校验通过的 bundle 文件把 hash 结果追加到一个本地索引文件里。每次加载前只从索引文件里读文件的路径和 hash索引缺失的直接判为异常触发重新下载。这个方案有个额外的好处如果玩家手机磁盘紧张导致写入不完整或者杀毒软件/系统清理工具误删了某个文件索引文件会立刻暴露问题。很多卡加载的问题根本原因是缓存目录里存在一个文件名正确但内容不完整的 bundle。因为文件名对索引也有记录但实际加载时文件已经损坏而你的代码里没有二次校验就直接崩了或者卡住。3.3 本地缓存的版本淘汰策略版本淘汰是另一个容易翻车的地方。常见误区是只保留当前版本的文件每次热更就把旧的目录删光。听起来简单但有个坑——如果新版资源有问题你想回滚到旧版本结果旧版本文件已经被删了只能整包重新下载。建议保留最近两个版本的资源目录当前版本和上一个版本。这样既能控制磁盘占用又保留了紧急回滚的能力。目录切换逻辑也简单下载新版本时写新目录全部校验完成后才更新current_version指针最后异步清理更老的目录。还要注意一个细节iOS 上persistentDataPath会被系统备份到 iCloudAssetBundle 文件完全没必要参与备份。建议在 iOS 平台对缓存目录设置NSURLIsExcludedFromBackupKey属性。这个不处理的话App Store 审核和用户存储空间都会出问题而且是那种很难排查的本地状态诡异问题。4. 一次完整的排查经历从卡进度到资源回滚4.1 现象与第一轮定位那次事故的具体现象是这样的运营后台报警登录后资源加载页的完成率从 99.2% 掉到 96.5%。客户端日志出现AssetBundle: Failed to load AssetBundle from path和Hash mismatch。重试多次依然失败但并不是所有玩家都中招集中在 Android 低端机和部分 iOS 设备上。我们的第一反应是查 CDN 状态。看了 CDN 的 URL 请求监控发现下载成功率确实有波动但源站和节点都没有大规模报错。带宽曲线正常回源失败率在 0.1% 以下。然后我们怀疑是不是新版本清单发错了对照了线上清单和本地测试版的清单版本号、hash 都一致。到这里CDN 侧的嫌疑被排除了大半。4.2 顺着链路往下本地缓存目录还原接下来我们把重点放到本地缓存。让运营抓了几台出问题设备的日志手动导出了缓存目录结构。对比之后发现了规律所有出问题设备上都存在1.4.2和1.4.1两个版本目录。1.4.2目录里的ui_mainpanel文件大小只有正常大小的 60% 左右。但1.4.2/manifest.json里记录的 hash 却是完整的。这说明什么说明这个文件下载的时候到一半连接断了但我们的下载逻辑没有正确处理未完成文件。而清单文件是完整下载的所以客户端认为自己拥有1.4.2版本资源跳过了重新下载直接加载结果失败。回看代码定位到问题我们的下载器是断点续传实现但判断文件是否存在且已下载时只看File.Exists没有核对文件长度和清单里记录的 size。连接中断后临时文件被保存为完整文件后续重试时直接跳过了这个文件导致残缺文件被当作有效资源。4.3 根因修复与防御加固这个问题的修复分两层第一层下载逻辑修正。断点续传必须在合并临时文件后对完整文件做 size hash 双重校验不通过就删除重下。临时文件命名和正式文件区分开避免半成品被误认为成品。第二层加载前校验。AssetBundle.LoadFromFile前通过索引文件核对 size 和 hash。这一步不能省因为下载校验只能防网络问题防不了运行时文件被系统清理、磁盘块损坏、或者越狱/ROOT 环境下文件被替换的情况。修复后我们又做了回滚演练把线上清单和 bundle 全部切回上一个版本验证客户端能否在保留旧缓存的情况下自动回退。结论是可以因为版本目录是独立的current_version指回1.4.1后加载逻辑完全正常。5. 三张排查清单遇到症状直接对照检查5.1 卡在加载进度条百试百灵的排查顺序客户端请求的清单 URL 是否返回 200内容里的版本号是否和线上一致。下载的 bundle 文件 size 是否和清单一致如果文件存在但 size 不对删掉重下。current_version指针是否和清单版本一致。检查Player.log里有没有OpenFile failed这类的系统级错误有的话检查目录读写权限。其中第 2 条最好做成自动校验不要留到加载时才暴露。存在本地但校验不过的 bundle一定要触发强制重新下载而不是静默跳过。这是我们踩出来的教训——很多团队为了省流量文件存在就跳过下载结果脏文件一直在问题永远复现。5.2 热更后老资源还在如果你发现某个 UI 或者某个模型热更之后显示的还是旧版先不要怀疑 Shader 问题大概率是加载路径不对检查加载代码里指定的 bundle 名称和清单里的name字段是否完全一致大小写和路径分隔符都算。检查 AssetBundleManifest 的依赖是不是完整挂上了依赖资源没更新主资源更新了也白搭最常见的就是图集和其他 bundle 的依赖关系断裂。检查是否用了LoadFromCacheAsync这个接口在某些情况下会命中旧缓存Unity 的 Caching 标识如果没正确失效拿到的就是老文件。最后一招把加载逻辑里的版本参数打出来看。很多资源显示老的其实就是加载入口传入了旧的 bundle 路径跟 CDN 一点关系都没有。5.3 热更后直接闪退或黑屏这类问题通常发生在资源加载成功后运行时数据不匹配。优先级从高到低排查新资源依赖了新增的 Shader但是 Shader 变体没有打进热更包。画面黑屏、颜色错乱多半是变体丢了。新 prefab 引用了新脚本但脚本没打进热更包或者程序集没随着热更更新反序列化直接挂。新资源用了新版本的 AssetBundle 压缩格式低版本客户端不兼容加载直接 crash。这里有一个比较隐蔽的场景Unity 2018 和 2019 的 AssetBundle 格式不完全兼容如果客户端用的 Unity 版本和服务端打包机版本不一致热更资源加载后容易出现各种 Type missing 的异常。打包机的 Unity 版本必须和客户端固定一致并且固定在构建机配置里不能多人手动打包。6. 排查工具与日志规范的实战建议6.1 客户端日志一定要带链路 ID热更新排查最怕的是日志里看不到这个请求是哪一次、对应哪个版本。以前我们遇到过玩家反馈资源加载失败日志里有错误信息但它重试了三次三次日志混在一起完全不知道哪一次对应哪一个文件。建议在热更模块里引入一个简单的链路标识。每次热更流程启动时生成一个update_trace_id随所有日志打出来。下载每个文件时日志里附带文件名、期望 hash、实际 hash、大小、耗时。线上收集日志时按trace_id聚合就能把一次完整的热更过程还原出来。具体日志字段可以参考[HotUpdate][trace7f3a9c] download start: ui_mainpanel, urlv1.4.2/ui_mainpanel, expected_hash7a3c9f2b [HotUpdate][trace7f3a9c] download finish: ui_mainpanel, size102400, actual_hash7a3c9f2b, duration312ms [HotUpdate][trace7f3a9c] verify pass: ui_mainpanel有了这个排查效率和以前完全不是一个量级。以前是拿着玩家反馈的截图到处猜现在直接看日志就能定位到是下载环节、校验环节还是加载环节。6.2 PC/Editor 底下专门做一套离线排查工具线上问题必须能在本地复现才有意义。我在项目里单独维护了一个排查用的小工具输入一个资源名工具会读取当前目录的清单文件打印出和该资源相关的所有依赖、大小、hash对比本地缓存文件的实际状态模拟一次加载输出加载耗时和是否成功。这个小工具帮我们排掉的问题至少有 4、5 个。其中有一个是某个 UI 界面加载时要依赖 11 个其他 bundle但清单里只有 10 个依赖关系第 11 个是代码里拼路径拼出来的加载的时候因为少了一个依赖界面显示空白且不报错。这种问题在代码里看一辈子都看不出来但跑一遍工具加载依赖列表一打印立刻原形毕露。6.3 热更资源包体大小异常时的排查思路如果你打出热更包后上传 CDN发现包体和上一次对比突然膨胀了好几倍先不要急着优化压缩重点查这几类是否误把不需要打 bundle 的场景/材质也打进去了最常见的是 StreamAssets 目录和 Bundle 目录混在一起。是否同一个资源被多个 bundle 重复包含。AssetBundle 依赖分析做得好不好直接体现在这里。是否把 Shader 原文件当普通资源打进了 bundle导致包体大增。正确的做法是用 ShaderVariantCollection 收集变体。包体异常不光浪费用户的流量还会拖慢 CDN 分发速度而且这个问题往往不会立刻报错但会在玩家体验上慢慢体现出来。上线前把包体大小纳入 CI 检查项设置阈值超了直接拦发布。这一步的成本极低但能挡住很多后续问题。7. 写在最后热更新排查的本质是状态管理做了这么多 AssetBundle 热更新安全排查最大的体会是热更系统本质上是一个分布式状态管理系统。远端有一个理想状态CDN 上的清单和资源本地有一个实际状态缓存文件、版本指针、索引记录排查的一切工作都是在让这两个状态收敛到一致。所以每次排查我都会先问自己几个问题客户端的当前版本是从哪里读出来的可靠吗本地的资源文件有没有可能被修改或污染有没有校验如果 CDN 上同时存在旧版和新版资源客户端靠什么机制保证选到正确的把这些问题的答案全部落到代码里用日志和数据来验证而不是凭感觉热更新就不会是那个时不时炸一下的模块。最后分享一个小技巧每次发热更包手动在本地模拟一次断网下载 中途恢复 二次热更的完整流程。看似很费时间但真的能提前暴露很多网络异常分支的 bug。我们那个断点续传问题就是在一次模拟中偶然发现的。测过一次你就知道自己的系统在极端情况下是什么表现了。
Unity AssetBundle热更新安全排查：从CDN到本地缓存的完整指南
1. 热更新链条上最容易出事的三个环节先说个真实场景。有一次线上版本发完热更包运营那边反馈有大概 3% 的玩家卡在启动资源加载界面日志里全是 AssetBundle 加载超时和 CRC 校验失败。当时第一反应是 CDN 节点出了问题结果查了一圈问题出在本地缓存的 manifest 版本和 CDN 上的清单对不上——一部分玩家上一个版本的热更资源没清理干净把新版本的文件名和 hash 索引全搞乱了。做 Unity AssetBundle 热更新最怕的就是这种看起来是网络问题实际上是本地状态问题的排查。热更新链条本身并不复杂核心就三条线CDN 清单分发远端服务器上存的版本索引、manifest 文件、资源 bundle 文件。这里决定该下载什么、该更新什么。下载与落盘客户端根据清单去拉取资源写入本地缓存目录。这里决定下载的文件对不对、全不全。本地缓存与加载Unity 的 AssetBundle 加载接口从本地文件或缓存系统中读取资源。这里决定加载到的是不是最新版本、有没有被污染。绝大多数热更新安全事故和线上故障都能归到这三个环节中的某一段。排查的时候如果一上来就盯着某一个点猛查很容易漏掉真正的根因。我的习惯是先画一条完整的数据流远程清单 - 版本比对 - 下载队列 - 缓存写入 - 加载验证。每一段都有自己独立的日志和校验点排查时逐个检查比盲目重试高效得多。2. CDN 侧排查从清单文件到 URL 校验2.1 先搞清楚清单文件里存的到底是什么AssetBundle 热更新的前提是有一个清单告诉客户端当前线上有哪些资源、每个资源的文件名、大小、哈希值、依赖关系。这个清单本身就是一个普通的文本或二进制文件常见做法是 JSON 格式里面大致长这样{ version: 1.4.2, bundles: [ { name: ui/mainpanel, md5: 7a3c9f2b1e..., size: 102400, dependencies: [ui/common, shared/textures] } ] }排查 CDN 侧问题的时候第一件事就是把客户端实际拿到的清单内容和 CDN 源站上的清单内容做对比。很多坑都出在客户端拿到的清单不是你以为的那份CDN 边缘节点缓存了旧版本清单TTL 没到新版本发出去之后部分节点还在吐旧数据。清单文件被 CDN 做了压缩处理客户端请求时带了 Accept-Encoding但解析逻辑没做对应解压。回源路径配置错误导致请求打到旧的源站目录。所以热更系统的 CDN 配置里清单文件必须设置为不缓存或者极短 TTL而 bundle 资源文件可以走长效缓存。如果项目用的是阿里云 OSS CDN 或者腾讯云 COS这类对象存储服务基本都支持指定 Cache-Control 头清单文件加no-cache资源文件加长缓存时间。2.2 URL 里的版本号和校验参数别省很多团队图省事下载 URL 直接写死资源名比如https://cdn.example.com/assetbundles/ui/mainpanel。这种方案在排查期最痛苦你没办法让客户端强制拉取某个特定版本的资源一旦 CDN 缓存过期策略出问题客户端拿到的永远是旧文件。我推荐的做法是把版本信息直接编码进 URL 路径或者查询参数https://cdn.example.com/assetbundles/1.4.2/ui/mainpanel https://cdn.example.com/assetbundles/ui/mainpanel?v1.4.2hash7a3c9f2b这样做的核心价值在于版本变了 URL 就变了CDN 的缓存自动失效不需要人为干预。而且 hash 参数可以作为下载完成后校验的一部分URL 里带 hash 还能顺带做 CDN 边缘鉴权。之前我们遇到过一个问题CDN 节点回源异常客户端拿到的 bundle 文件是少数几个节点上的脏数据但因为 URL 里带了预期 hash客户端下载完先比对不一致就直接报错并触发重试而不是把脏资源直接用起来——这一步挽救了那次发布。需要注意URL 带版本号有一个副作用旧版本资源在 CDN 上不会被主动清理久而久之存储量越来越大。解决方式是定期跑一个 CDN 刷新或者目录清理任务但这是运维侧的事不影响客户端逻辑。2.3 清单校验不能只靠依赖 MD5只比对 bundle 文件的 MD5 是不够的。清单本身也必须做签名校验。做法很简单在服务端生成清单时用私钥对清单内容做签名客户端内置公钥加载清单时先验证签名再解析内容。之前见过一个项目资源被人恶意篡改后在各个游戏群传播玩家挂上代理此类网络代理场景且不做展开加载恶意资源导致客户端出现异常弹窗。用户拿到那套资源的第一个入口就是热更清单没有签名校验。所以清单签名不是一个可选项凡是有真实用户的热更新项目这一步必须做。签名算法选 HMAC-SHA256 就好配上每个客户端的随机盐能有效防止请求重放。3. 本地缓存排查目录结构、加载接口与生命周期3.1 先弄清你的缓存是 Caching 系统还是自研目录Unity 的 AssetBundle 缓存有两条路线使用Caching.GetCache/Caching.AddCache管理的 Unity 内置缓存系统。自己在Application.persistentDataPath下面建目录用AssetBundle.LoadFromFile/LoadFromMemory加载。两条路线各有各的坑。用内置缓存系统好处是 Unity 帮你处理了文件命名和索引坏处是排查时你很难直接看到文件。缓存文件散落在系统目录里你没法直观地确认它到底是什么版本。而且 Unity 的 Caching 系统在不同版本之间行为有差异特别是 2019、2020 到 2021 之后的版本Caching.ready状态和同步接口的行为都有变化。自研目录的优点是可排查性强文件结构完全可控缺点是下载、校验、清理全都要自己写。我个人的建议是如果项目团队有排查能力尽量自研缓存目录。不是因为内置系统不好而是因为热更新出问题时一个透明的目录结构能救命。以我们项目为例缓存目录长这样persistentDataPath/AssetBundles/ ├── 1.4.2/ │ ├── manifest.json │ ├── ui_mainpanel │ ├── ui_common │ └── shared_textures ├── 1.4.1/ │ ├── manifest.json │ └── ui_oldpanel └── current_versioncurrent_version是一个文本文件记录当前活跃的版本号加载时先读它再去对应版本目录里找资源。3.2 缓存完整性与残留文件排查本地缓存最常见的安全隐患是文件不完整或者文件被污染。Unity 的LoadFromFile接口对损坏文件的行为是直接返回 null不会给你报具体原因。这时候就需要你有一个校验机制在下载完成后立刻做一次完整性检查而不是等到加载时才发现。我们的做法是三步下载完成后用清单里的 MD5/SHA256 做对比。校验通过的 bundle 文件把 hash 结果追加到一个本地索引文件里。每次加载前只从索引文件里读文件的路径和 hash索引缺失的直接判为异常触发重新下载。这个方案有个额外的好处如果玩家手机磁盘紧张导致写入不完整或者杀毒软件/系统清理工具误删了某个文件索引文件会立刻暴露问题。很多卡加载的问题根本原因是缓存目录里存在一个文件名正确但内容不完整的 bundle。因为文件名对索引也有记录但实际加载时文件已经损坏而你的代码里没有二次校验就直接崩了或者卡住。3.3 本地缓存的版本淘汰策略版本淘汰是另一个容易翻车的地方。常见误区是只保留当前版本的文件每次热更就把旧的目录删光。听起来简单但有个坑——如果新版资源有问题你想回滚到旧版本结果旧版本文件已经被删了只能整包重新下载。建议保留最近两个版本的资源目录当前版本和上一个版本。这样既能控制磁盘占用又保留了紧急回滚的能力。目录切换逻辑也简单下载新版本时写新目录全部校验完成后才更新current_version指针最后异步清理更老的目录。还要注意一个细节iOS 上persistentDataPath会被系统备份到 iCloudAssetBundle 文件完全没必要参与备份。建议在 iOS 平台对缓存目录设置NSURLIsExcludedFromBackupKey属性。这个不处理的话App Store 审核和用户存储空间都会出问题而且是那种很难排查的本地状态诡异问题。4. 一次完整的排查经历从卡进度到资源回滚4.1 现象与第一轮定位那次事故的具体现象是这样的运营后台报警登录后资源加载页的完成率从 99.2% 掉到 96.5%。客户端日志出现AssetBundle: Failed to load AssetBundle from path和Hash mismatch。重试多次依然失败但并不是所有玩家都中招集中在 Android 低端机和部分 iOS 设备上。我们的第一反应是查 CDN 状态。看了 CDN 的 URL 请求监控发现下载成功率确实有波动但源站和节点都没有大规模报错。带宽曲线正常回源失败率在 0.1% 以下。然后我们怀疑是不是新版本清单发错了对照了线上清单和本地测试版的清单版本号、hash 都一致。到这里CDN 侧的嫌疑被排除了大半。4.2 顺着链路往下本地缓存目录还原接下来我们把重点放到本地缓存。让运营抓了几台出问题设备的日志手动导出了缓存目录结构。对比之后发现了规律所有出问题设备上都存在1.4.2和1.4.1两个版本目录。1.4.2目录里的ui_mainpanel文件大小只有正常大小的 60% 左右。但1.4.2/manifest.json里记录的 hash 却是完整的。这说明什么说明这个文件下载的时候到一半连接断了但我们的下载逻辑没有正确处理未完成文件。而清单文件是完整下载的所以客户端认为自己拥有1.4.2版本资源跳过了重新下载直接加载结果失败。回看代码定位到问题我们的下载器是断点续传实现但判断文件是否存在且已下载时只看File.Exists没有核对文件长度和清单里记录的 size。连接中断后临时文件被保存为完整文件后续重试时直接跳过了这个文件导致残缺文件被当作有效资源。4.3 根因修复与防御加固这个问题的修复分两层第一层下载逻辑修正。断点续传必须在合并临时文件后对完整文件做 size hash 双重校验不通过就删除重下。临时文件命名和正式文件区分开避免半成品被误认为成品。第二层加载前校验。AssetBundle.LoadFromFile前通过索引文件核对 size 和 hash。这一步不能省因为下载校验只能防网络问题防不了运行时文件被系统清理、磁盘块损坏、或者越狱/ROOT 环境下文件被替换的情况。修复后我们又做了回滚演练把线上清单和 bundle 全部切回上一个版本验证客户端能否在保留旧缓存的情况下自动回退。结论是可以因为版本目录是独立的current_version指回1.4.1后加载逻辑完全正常。5. 三张排查清单遇到症状直接对照检查5.1 卡在加载进度条百试百灵的排查顺序客户端请求的清单 URL 是否返回 200内容里的版本号是否和线上一致。下载的 bundle 文件 size 是否和清单一致如果文件存在但 size 不对删掉重下。current_version指针是否和清单版本一致。检查Player.log里有没有OpenFile failed这类的系统级错误有的话检查目录读写权限。其中第 2 条最好做成自动校验不要留到加载时才暴露。存在本地但校验不过的 bundle一定要触发强制重新下载而不是静默跳过。这是我们踩出来的教训——很多团队为了省流量文件存在就跳过下载结果脏文件一直在问题永远复现。5.2 热更后老资源还在如果你发现某个 UI 或者某个模型热更之后显示的还是旧版先不要怀疑 Shader 问题大概率是加载路径不对检查加载代码里指定的 bundle 名称和清单里的name字段是否完全一致大小写和路径分隔符都算。检查 AssetBundleManifest 的依赖是不是完整挂上了依赖资源没更新主资源更新了也白搭最常见的就是图集和其他 bundle 的依赖关系断裂。检查是否用了LoadFromCacheAsync这个接口在某些情况下会命中旧缓存Unity 的 Caching 标识如果没正确失效拿到的就是老文件。最后一招把加载逻辑里的版本参数打出来看。很多资源显示老的其实就是加载入口传入了旧的 bundle 路径跟 CDN 一点关系都没有。5.3 热更后直接闪退或黑屏这类问题通常发生在资源加载成功后运行时数据不匹配。优先级从高到低排查新资源依赖了新增的 Shader但是 Shader 变体没有打进热更包。画面黑屏、颜色错乱多半是变体丢了。新 prefab 引用了新脚本但脚本没打进热更包或者程序集没随着热更更新反序列化直接挂。新资源用了新版本的 AssetBundle 压缩格式低版本客户端不兼容加载直接 crash。这里有一个比较隐蔽的场景Unity 2018 和 2019 的 AssetBundle 格式不完全兼容如果客户端用的 Unity 版本和服务端打包机版本不一致热更资源加载后容易出现各种 Type missing 的异常。打包机的 Unity 版本必须和客户端固定一致并且固定在构建机配置里不能多人手动打包。6. 排查工具与日志规范的实战建议6.1 客户端日志一定要带链路 ID热更新排查最怕的是日志里看不到这个请求是哪一次、对应哪个版本。以前我们遇到过玩家反馈资源加载失败日志里有错误信息但它重试了三次三次日志混在一起完全不知道哪一次对应哪一个文件。建议在热更模块里引入一个简单的链路标识。每次热更流程启动时生成一个update_trace_id随所有日志打出来。下载每个文件时日志里附带文件名、期望 hash、实际 hash、大小、耗时。线上收集日志时按trace_id聚合就能把一次完整的热更过程还原出来。具体日志字段可以参考[HotUpdate][trace7f3a9c] download start: ui_mainpanel, urlv1.4.2/ui_mainpanel, expected_hash7a3c9f2b [HotUpdate][trace7f3a9c] download finish: ui_mainpanel, size102400, actual_hash7a3c9f2b, duration312ms [HotUpdate][trace7f3a9c] verify pass: ui_mainpanel有了这个排查效率和以前完全不是一个量级。以前是拿着玩家反馈的截图到处猜现在直接看日志就能定位到是下载环节、校验环节还是加载环节。6.2 PC/Editor 底下专门做一套离线排查工具线上问题必须能在本地复现才有意义。我在项目里单独维护了一个排查用的小工具输入一个资源名工具会读取当前目录的清单文件打印出和该资源相关的所有依赖、大小、hash对比本地缓存文件的实际状态模拟一次加载输出加载耗时和是否成功。这个小工具帮我们排掉的问题至少有 4、5 个。其中有一个是某个 UI 界面加载时要依赖 11 个其他 bundle但清单里只有 10 个依赖关系第 11 个是代码里拼路径拼出来的加载的时候因为少了一个依赖界面显示空白且不报错。这种问题在代码里看一辈子都看不出来但跑一遍工具加载依赖列表一打印立刻原形毕露。6.3 热更资源包体大小异常时的排查思路如果你打出热更包后上传 CDN发现包体和上一次对比突然膨胀了好几倍先不要急着优化压缩重点查这几类是否误把不需要打 bundle 的场景/材质也打进去了最常见的是 StreamAssets 目录和 Bundle 目录混在一起。是否同一个资源被多个 bundle 重复包含。AssetBundle 依赖分析做得好不好直接体现在这里。是否把 Shader 原文件当普通资源打进了 bundle导致包体大增。正确的做法是用 ShaderVariantCollection 收集变体。包体异常不光浪费用户的流量还会拖慢 CDN 分发速度而且这个问题往往不会立刻报错但会在玩家体验上慢慢体现出来。上线前把包体大小纳入 CI 检查项设置阈值超了直接拦发布。这一步的成本极低但能挡住很多后续问题。7. 写在最后热更新排查的本质是状态管理做了这么多 AssetBundle 热更新安全排查最大的体会是热更系统本质上是一个分布式状态管理系统。远端有一个理想状态CDN 上的清单和资源本地有一个实际状态缓存文件、版本指针、索引记录排查的一切工作都是在让这两个状态收敛到一致。所以每次排查我都会先问自己几个问题客户端的当前版本是从哪里读出来的可靠吗本地的资源文件有没有可能被修改或污染有没有校验如果 CDN 上同时存在旧版和新版资源客户端靠什么机制保证选到正确的把这些问题的答案全部落到代码里用日志和数据来验证而不是凭感觉热更新就不会是那个时不时炸一下的模块。最后分享一个小技巧每次发热更包手动在本地模拟一次断网下载 中途恢复 二次热更的完整流程。看似很费时间但真的能提前暴露很多网络异常分支的 bug。我们那个断点续传问题就是在一次模拟中偶然发现的。测过一次你就知道自己的系统在极端情况下是什么表现了。