做Unity客户端开发的朋友大概率都碰过这么一档子事线上包发出去CDN也传好了结果用户那边一进游戏就卡在加载界面或者明明提示更新成功加载的还是老资源。我最近手头一个项目就碰到了类似问题排查了一圈最后发现坑不在打AB包而是在从CDN清单到本地缓存这条链路里。这篇文章就把“Unity AssetBundle热更新安全排查”这件事从头到尾拆开讲。围绕CDN清单、资源下载、本地缓存这三个核心环节我会结合自己的排障过程把每一步的检查思路、关键参数、常见坑点都写清楚。不管你是刚接手游项目的新人还是被线上问题折腾过几次的客户端开发这篇文章应该都能帮你少走几段弯路。1. 热更新链路全景从构建到加载的完整视图1.1 AssetBundle热更新的基本链路AssetBundle热更新的思路其实不复杂客户端启动后先去服务器比对版本拿到最新资源和资源清单再下载缺失或变更的AB包落盘到本地缓存后续加载时优先从本地缓存读取。链路看起来清晰但每个节点都可能出问题。拆开来看这条链路至少包含六个环节版本号接口校验、CDN清单获取、AB包下载、本地缓存写入、加载器初始化、资源加载与依赖解析。我排查问题时习惯把链路画成一条流水线每个环节只做一件事出了问题就能快速定位到具体位置。版本号接口负责告诉客户端“现在该用哪个版本”。CDN清单则决定“这个版本下有哪些资源、每个资源的hash值是多少”。AB包下载环节负责从CDN拉取实际资源本地缓存负责存下已下载的包最后的加载器则根据依赖关系把资源加载进内存。任何一个环节被篡改、缺失或配置错误都会导致资源加载异常。1.2 为什么“安全排查”要沿着这条链路做我给项目做排查时最先发现的一个现象是同一个AB包不同用户加载出来效果不一样。有人是新资源有人是旧资源还有人干脆加载失败。如果只看加载器代码根本找不到原因因为问题出在链路的前半段——CDN清单和本地缓存的状态不一致。安全排查的核心思路是不信任链路中任何单一来源。CDN清单可能被缓存策略影响返回旧版本本地缓存可能残留上一次版本的脏数据下载过程可能被截断但校验不严导致坏包落盘。沿着CDN清单到本地缓存这条链路逐一校验才能找出真正的问题点。1.3 排查前需要准备的检查项清单正式开始排查之前我建议先把下面这些信息准备好能省不少事项目的AB包命名规范是AssetBundle名还是带hash的完整名CDN的缓存刷新策略是否配置了版本目录隔离本地的资源缓存目录结构用的是persistentDataPath还是临时目录版本号接口的返回数据结构字段含义是否清晰加载器的依赖解析方式是否按Manifest加载这些信息决定了排查的方向。比如AB包命名规范如果是纯名称不带hash那么CDN缓存导致的旧包问题几乎必然出现因为同名文件只要没失效CDN就会一直返回旧版本。2. CDN清单环节的深度排查2.1 清单文件的结构与核心字段Unity打包AB时每个平台会生成一个与平台同名的Manifest文件里面记录了所有AB包的名称、hash、依赖关系。我之前遇到一个项目把整个AB根目录的Manifest直接当成CDN清单下发结果客户端每次启动都要解析一份几MB的JSON启动速度肉眼可见地变慢。更关键的是Manifest里的hash字段才是安全校验的核心。客户端下载AB包时不能只依赖文件名判断是否更新必须拿本地缓存的hash与CDN清单里的hash做比对。如果hash不一致哪怕文件存在也要重新下载。我见过不少团队为了省流量只比对文件名就跳过下载结果资源永远停留在旧版本。清单文件在CDN上存放时我建议单独放在一个带版本号的目录下而不是覆盖式更新。比如/cdn/assetbundles/v102/manifest.hash这样的路径。这样CDN的缓存也好配置即便客户端缓存了旧清单版本号变了也能强制刷新。2.2 清单文件的完整性校验清单文件本身也面临被篡改的风险。CDN这层如果被劫持或者被注入客户端拿到恶意清单后会把恶意AB包当成正常资源下载。所以我在排查时有一个必做动作给清单文件加签名或者做hash双重校验。具体做法是构建AB包时额外生成一个manifest.sig文件内容是清单文件的签名值。客户端下载清单后先用内置公钥验证签名验证通过才允许解析。如果签名验证失败直接走兜底逻辑使用本地缓存的上一份可用清单而不是直接崩溃或重新下载。签名校验的代价很小一次RSA验证大概几毫秒但对安全性的提升非常明显。我曾经在一个外包项目里见过没有签名校验的清单配置测试环境还好一旦CDN被恶意缓存命中整个热更新资源都能被替换属于严重安全事故。2.3 版本号与清单的对应关系排查版本号的匹配逻辑也容易出坑。项目里常见做法是启动时请求version.json返回remoteVersion和remoteManifestUrl。客户端拿本地版本号和远程版本号做比较决定是否需要更新。这一步比较的时候我建议统一用整数版本号而不是字符串。字符串比较在版本号超过两位数时会出现“v100小于v99”之类的低级错误。还有个容易被忽略的点版本号接口本身也建议做缓存穿透保护。CDN对版本接口配置了强缓存的话客户端永远拿不到最新版本号。我排查过一个线上问题版本接口在CDN上缓存了10分钟导致发版后用户最长10分钟内无法触发更新后台看着用户全在线其实版本全是旧的。所以版本号接口在CDN上的Cache-Control建议设置为no-cache或者极短时间比如30秒。如果担心CDN节点回源压力大可以让源站做一次缓存但客户端侧的版本接口一定要保证新鲜度。2.4 清单差异对比的推荐实现客户端拿到新清单后需要和本地缓存的旧清单做差异对比决定哪些AB包需要下载。这个对比逻辑我推荐放在子线程里做避免阻塞主线程引起卡顿。对比的核心不是遍历所有AB包而是先比对hash字典。具体做法是将新旧清单中的AB包路径作为keyhash值作为value构建两个字典然后求差集。差集中的AB包就是待下载集合。如果AB包本身没有变化直接沿用本地文件不用重复下载。这里有个性能细节Manifest解析后依赖关系是树形结构但差异对比一定要把“依赖链上的变化包”也纳入待下载列表。A包依赖B包B包变了A包也必须重新下载否则加载A时引用旧依赖会出现资源错乱。我实际排查中见过只更新了单个资源包忘了更新其依赖链导致UI贴图错位的问题就是因为差异对比时没有扩散依赖关系。3. 下载过程中的CDN链路与传输安全3.1 CDN缓存策略对热更新的影响CDN是热更新最依赖的传输层但也是排查中最让人头疼的一环。最常见的坑是AB包上传到CDN后CDN节点没有回源更新导致不同地区用户拿到不同版本资源。要解决这个问题不能只靠上传文件还得主动刷新CDN缓存或者用带版本号的目录隔离。我推荐使用版本号目录隔离的方式。简单说每次发版资源都上传到一个全新的路径下比如/assetbundles/v103/。这样CDN的旧缓存路径里没有新文件客户端访问新路径时必然回源不会命中旧缓存。这种做法的代价是存储空间稍大一点但换来的是更新流程的确定性和安全性很划算。如果项目因为某种原因无法使用版本目录必须覆盖式更新那么每次发版后都要记得调用CDN的API做目录刷新。我踩过坑有一次忘了刷CDN缓存测试同学改了AB包重传结果还是旧资源排查到深夜才发现是CDN缓存没刷新这种情况其实很常见。3.2 HTTPS与明文传输的安全隐患资源传输走HTTPS还是HTTP在这条链路上差别很大。HTTP明文传输意味着中间节点可以看到资源内容可以篡改后转发客户端收到的AB包是否完整、是否被注入恶意代码完全没有保障。热更新资源本质上是可执行代码逻辑的一部分比如Lua脚本、AssetBundle里的预制体一旦被篡改后果很严重。所以排查的第一要求就是AB包下载和清单获取必须走HTTPS。市面上所有正规CDN都支持免费HTTPS证书这一步的成本极低但收益很大。如果项目还停留在HTTP建议把升级HTTPS作为热更新安全改造的第一步没有商量的余地。3.3 下载中断、重试与断点续传AB包下载过程中移动网络切换、弱网、后台切换都可能中断。如果下载中断后直接放弃用户会反复下载同一个大包体验很差。更严重的情况是下载中断后文件不完整但客户端没做完整性校验照样放行写入缓存之后加载时就会出现损坏资源的表现。我给项目做排查时要求AB下载模块必须满足三个条件支持断点续传记录已下载字节数下载完成后校验文件大小和hash核对无误才写入缓存如果校验失败删除临时文件重新下载而不是直接覆盖。断点续传的实现依赖HTTP Range头。下载前先请求文件元数据拿到总大小然后从本地临时文件的当前大小开始请求剩余部分。UnityWebRequest的SetRequestHeader(Range, $bytes{start}-)字段就是干这个的。实测在弱网环境下断点续传能减少大量重复流量尤其是那种上百MB的场景包效果非常明显。3.4 下载超时与重试策略的合理参数下载重试是个双刃剑。重试太频繁CDN压力大封IP风险高重试太少用户网络一抖动就失败体验差。我在项目中习惯用指数退避策略第一次失败后等2秒第二次等4秒第三次等8秒最多重试3到5次。这个策略的核心是不给CDN源站造成持续压力同时兼顾用户体验。超时设置也要分阶段看待。连接阶段TCP握手和TLS握手建议超时设置在10到15秒数据读取阶段建议每30秒检查一次是否有数据流动。如果30秒内没有任何字节到达说明连接可能已死需要触发重连或重试。我之前遇到过一个问题连接成功了但服务端一直没有返回数据如果只设置了总超时时间用户会一直卡在下载界面日志里什么都没有后来改成“读超时”才解决。超时参数这里给个我正常用的配置供参考DNS解析超时不单独设置跟随连接超时连接超时10秒读超时无数据空闲30秒最大重试次数3次重试间隔2秒、4秒、8秒4. 本地缓存安全与完整性核验4.1 本地缓存目录的正确选择Unity热更新资源的缓存目录常规做法是放在Application.persistentDataPath下。这个目录在不同平台上有不同的实际路径在Android上是/sdcard/Android/data/包名/files在iOS上是沙盒Documents目录。这个目录的优点是系统保证应用私有不需要额外权限卸载后自动清除不会污染用户设备。有些项目图省事把AB包直接放Application.temporaryCachePath。这个目录系统可能随时清理热跟新资源随时可能被清掉用户玩到一半资源丢失只能重新下载。我排查过的项目里有因为缓存目录选错导致资源反复下载的属于基础配置问题改进来也很容易。还有一点不要在代码里拼接绝对路径写死到外部存储。Android平台外部存储权限敏感而且不同厂商对权限的处理不一致容易触发崩溃或者适配问题。一切文件操作都走Unity的持久化目录API这是最稳妥的做法。4.2 本地缓存的写权限与进程安全本地缓存的写入操作要注意进程安全问题。同一时间只能有一个下载任务在写同一个缓存文件否则会互相覆盖产生损坏包。UnityWebRequest的downloadHandler是异步回调多任务并发下载时回调里的文件写操作要加锁控制或者在状态机里严格管理单个文件的下载状态。我实际遇到过一个诡异问题两个AB包文件同时写同一个缓存路径结果加载时资源时对时不对。后来排查发现是下载调度器里同一个请求被重复加入下载队列触发了并发写同一文件。解决办法很简单下载开始前检查该文件是否已在下载列表或已存在于缓存中双重判断后再决定是否加入队列。4.3 缓存文件的有效性校验与哈希比对本地缓存的AB包不能默认它是安全完整的。文件的hash值必须和CDN清单里的hash一致才能被加载器使用。这个校验建议放在两个时机一是下载完成落盘时校验二是加载器读取前校验。第一个校验防下载损坏第二个校验防缓存被其他程序篡改或磁盘异常。有人担心hash校验会影响加载性能。实际测试中对单文件执行一次SHA1或MD5校验对象是几十MB的AB包耗时在几十毫秒到一两百毫秒之间。而AssetBundle.LoadFromFile本身加载就需要几十毫秒加上hash校验的代价完全可接受。但如果追求极致可以对AB包做分块hash校验只校验文件头、文件尾和中间固定位置的数据块能进一步降低耗时。4.4 缓存清理策略与防回滚措施本地缓存的清理策略不能写得太激进。最简单的做法是保留当前版本所需的所有AB包额外保留上一版本的所有AB包作为滚动回退。如果磁盘空间不够优先清理下载时间最早且不在当前清单中的资源。千万不要在启动时全量清理缓存目录一旦清理后下载失败用户连回退的机会都没有。防回滚是另一个安全点。CDN清单下发新版本后客户端要把本地缓存的旧版本号一并更新。如果本地版本号可以被外部改动攻击者就能降级版本强制客户端加载旧的、可能存在漏洞的资源。所以本地版本号建议不要明文存在可写目录文件中可以集成到本地配置类管理中读取时做合法性校验发现问题就重置为初始状态触发全量更新。我一般这样设计本地缓存目录结构persistentDataPath/ ├── hotupdate/ │ ├── version.dat // 本地版本号 │ ├── manifest.hash // 最近一次可用清单hash │ ├── bundles/ │ │ ├── 路径哈希名1.ab │ │ ├── 路径哈希名2.ab这里有个细节缓存文件命名不能用原始路径名因为原始路径含层级目录文件名还可能带特殊字符。我习惯用AB包的AssetBundle名做MD5得到32位小写哈希作为缓存文件名。这样既能保证唯一性也规避了文件名合法性校验问题。5. 实操排查流程从现象到根因的定位方法5.1 排查第一步确认用户实际版本与清单hash接到热更新问题反馈后不要直接看加载器代码。第一步先让现场的同学或者测试复现问题环境拿到用户当前本地版本号、CDN清单版本号、以及实际加载成功的AB包hash。这三个信息可以快速判定问题出在哪一层。对比逻辑其实很简单本地版本号和CDN版本号不一致说明客户端未触发更新逻辑版本号一致但加载内容异常说明下载或缓存层有问题版本号一致且本地hash正确但加载内容还是旧资源说明加载器或依赖解析有bug。很多时候问题会自动定位到具体层级。给用户设备打一个日志标记把版本信息输出到日志文件再回传是定位热更新问题最有效的手段。我这边排查时都会先让测试开日志没有日志的话很多现场没法复现效率至少慢一半。5.2 全链路日志埋点的最小方案热更新排查离不开日志。日志埋点不需要多复杂但关键节点必须有输出。我习惯在每个环节加一行结构化日志包含时间戳、当前版本号、目标版本号、关键hash值、结果状态。这样回传日志后很快就能还原出完整的更新过程。比如下载阶段我会输出开始下载、请求URL、文件大小、已下载字节数、校验hash、写入路径、校验结果。加载阶段输出请求加载AB包名、命中缓存路径、文件hash、加载耗时。这些日志看起来啰嗦但线上排查时就是定位神器。5.3 模拟弱网、篡改、缓存过期三类异常场景排查热更新安全问题时我一般会在测试环境里主动构造三类异常场景。弱网场景用网络工具限制带宽和丢包率验证断点续传、超时重试、损坏包重新下载是否符合预期。篡改场景手动修改本地缓存中的AB包文件或者修改CDN清单的hash值看客户端是否能够识别并拒绝加载。缓存过期场景在CDN上设置较短的缓存时间或者在版本目录上做覆盖更新看客户端是否会出现旧资源残留。这三类场景覆盖了从CDN清单到本地缓存的主要风险点。能在这三类场景下正常工作的热更新系统基本可以认为链路安全性和健壮性都比较过关。5.4 一份可用于排查记录的排查表格排查过程中我建议用表格记录每一步的结果便于复盘和交接。表格可以做成这样排查阶段检查项预期结果实际结果结论版本接口返回版本号位数整数字符串带v前缀有风险CDN清单hash字段缺失每个AB包均有hash部分缺失补全构建逻辑下载链路HTTPS配置全部走HTTPS混合HTTP修复协议本地缓存文件hash校验校验通过才加载未校验增加校验逻辑加载器依赖链扩散依赖变更自动更新未处理依赖修复依赖逻辑这个表格本身不复杂但每一条都对应着实际代码或配置的修改项。排查结束后表格留下的就是一份可执行的技术改造清单。6. 常见问题速查与实战配套建议6.1 典型故障现象与可能原因对照表我把实际排查中遇到的典型问题整理成了速查表方便遇到类似问题时直接对照节省定位时间故障现象可能原因排查建议用户版本是新的但加载旧资源CDN缓存旧文件检查版本目录隔离刷新CDN缓存加载AB包报错资源损坏下载中断未校验hash增加落盘前完整性校验部分用户卡在更新界面版本接口被CDN缓存版本接口禁用强缓存更新一次后反复更新本地清单未持久化将清单hash写入version.dat依赖资源错乱差异对比未扩散依赖链将依赖变更包纳入下载列表缓存目录写入失败目录路径不可写改用persistentDataPath这个表格里的每一条基本都对应我前面章节提到的排查点。真出了问题按表格逐条核对大概率能在半小时内找到根因。6.2 排查过程中最容易踩的坑排查热更新问题时有几个坑我自己反复踩过这里专门记一笔。第一个坑是只看客户端日志不看CDN日志。很多资源问题在CDN侧会有非常明确的线索比如回源比例、缓存命中率、404数量。客户端日志只能告诉你“加载失败”CDN日志能告诉你“哪个节点在什么时间返回了哪个文件”。配合两边日志查定位效率翻倍。第二个坑是忘记校验AB包的依赖hash。单体AB包hash对了但依赖的另一个AB包已经变更加载出来还是错的。差异对比时务必把依赖链上的变化包一并纳入下载列表这一点我在第三章和第五章都强调过。第三个坑是盲目清理本地缓存。有些同事遇到资源损坏问题第一反应是让用户清理缓存重新下载。如果是偶发问题这会掩盖真实缺陷比如下载中断、校验逻辑缺失。正确的做法是先定位根因修复代码缓存清理只作为兜底手段。6.3 给中小团队的热更新安全升级建议如果你的项目还在用比较朴素的AB更新方式也就是直接比较版本号、下载即用、不校验任何hash我个人建议按这个优先级推进改造第一步给清单文件加签名校验。这一步不需要改架构只是构建流程多生成一个签名文件客户端多一次验证。收益极高成本极低。第二步AB包下载完成后做hash校验。这一步能挡住绝大多数损坏包问题也是排查链路中最关键的防线。第三步CDN走版本目录隔离加HTTPS。配置工作不大但能彻底解决缓存旧资源和传输被篡改两大类问题。第四步本地缓存校验加防回滚。等前几步完成了再投入因为防回滚依赖清单hash和版本号管理的一致性。6.4 关于日志与监控的最后一件事热更新链路里日志和监控不是可选项是必需品。别等到线上出了问题再补日志那时你手里没有任何现场证据排查会很艰难。我从一个线上事故里学到的教训是版本对比结果、清单hash校验结果、每个AB包的下载状态这三类日志必须默认打开线上环境也保留。另外可以做一个简单的数据上报统计热更新成功率、平均下载耗时、待下载AB包数量、失败重试次数。这些数据平时看着不起眼一旦发版后出现问题它们能最快告诉你影响范围和分布情况。热更新安全排查这件事本质上不是等出了问题再去修而是把每条链路的可靠性做扎实让问题在发生前就被设计挡住。
做Unity客户端开发的朋友大概率都碰过这么一档子事线上包发出去CDN也传好了结果用户那边一进游戏就卡在加载界面或者明明提示更新成功加载的还是老资源。我最近手头一个项目就碰到了类似问题排查了一圈最后发现坑不在打AB包而是在从CDN清单到本地缓存这条链路里。这篇文章就把“Unity AssetBundle热更新安全排查”这件事从头到尾拆开讲。围绕CDN清单、资源下载、本地缓存这三个核心环节我会结合自己的排障过程把每一步的检查思路、关键参数、常见坑点都写清楚。不管你是刚接手游项目的新人还是被线上问题折腾过几次的客户端开发这篇文章应该都能帮你少走几段弯路。1. 热更新链路全景从构建到加载的完整视图1.1 AssetBundle热更新的基本链路AssetBundle热更新的思路其实不复杂客户端启动后先去服务器比对版本拿到最新资源和资源清单再下载缺失或变更的AB包落盘到本地缓存后续加载时优先从本地缓存读取。链路看起来清晰但每个节点都可能出问题。拆开来看这条链路至少包含六个环节版本号接口校验、CDN清单获取、AB包下载、本地缓存写入、加载器初始化、资源加载与依赖解析。我排查问题时习惯把链路画成一条流水线每个环节只做一件事出了问题就能快速定位到具体位置。版本号接口负责告诉客户端“现在该用哪个版本”。CDN清单则决定“这个版本下有哪些资源、每个资源的hash值是多少”。AB包下载环节负责从CDN拉取实际资源本地缓存负责存下已下载的包最后的加载器则根据依赖关系把资源加载进内存。任何一个环节被篡改、缺失或配置错误都会导致资源加载异常。1.2 为什么“安全排查”要沿着这条链路做我给项目做排查时最先发现的一个现象是同一个AB包不同用户加载出来效果不一样。有人是新资源有人是旧资源还有人干脆加载失败。如果只看加载器代码根本找不到原因因为问题出在链路的前半段——CDN清单和本地缓存的状态不一致。安全排查的核心思路是不信任链路中任何单一来源。CDN清单可能被缓存策略影响返回旧版本本地缓存可能残留上一次版本的脏数据下载过程可能被截断但校验不严导致坏包落盘。沿着CDN清单到本地缓存这条链路逐一校验才能找出真正的问题点。1.3 排查前需要准备的检查项清单正式开始排查之前我建议先把下面这些信息准备好能省不少事项目的AB包命名规范是AssetBundle名还是带hash的完整名CDN的缓存刷新策略是否配置了版本目录隔离本地的资源缓存目录结构用的是persistentDataPath还是临时目录版本号接口的返回数据结构字段含义是否清晰加载器的依赖解析方式是否按Manifest加载这些信息决定了排查的方向。比如AB包命名规范如果是纯名称不带hash那么CDN缓存导致的旧包问题几乎必然出现因为同名文件只要没失效CDN就会一直返回旧版本。2. CDN清单环节的深度排查2.1 清单文件的结构与核心字段Unity打包AB时每个平台会生成一个与平台同名的Manifest文件里面记录了所有AB包的名称、hash、依赖关系。我之前遇到一个项目把整个AB根目录的Manifest直接当成CDN清单下发结果客户端每次启动都要解析一份几MB的JSON启动速度肉眼可见地变慢。更关键的是Manifest里的hash字段才是安全校验的核心。客户端下载AB包时不能只依赖文件名判断是否更新必须拿本地缓存的hash与CDN清单里的hash做比对。如果hash不一致哪怕文件存在也要重新下载。我见过不少团队为了省流量只比对文件名就跳过下载结果资源永远停留在旧版本。清单文件在CDN上存放时我建议单独放在一个带版本号的目录下而不是覆盖式更新。比如/cdn/assetbundles/v102/manifest.hash这样的路径。这样CDN的缓存也好配置即便客户端缓存了旧清单版本号变了也能强制刷新。2.2 清单文件的完整性校验清单文件本身也面临被篡改的风险。CDN这层如果被劫持或者被注入客户端拿到恶意清单后会把恶意AB包当成正常资源下载。所以我在排查时有一个必做动作给清单文件加签名或者做hash双重校验。具体做法是构建AB包时额外生成一个manifest.sig文件内容是清单文件的签名值。客户端下载清单后先用内置公钥验证签名验证通过才允许解析。如果签名验证失败直接走兜底逻辑使用本地缓存的上一份可用清单而不是直接崩溃或重新下载。签名校验的代价很小一次RSA验证大概几毫秒但对安全性的提升非常明显。我曾经在一个外包项目里见过没有签名校验的清单配置测试环境还好一旦CDN被恶意缓存命中整个热更新资源都能被替换属于严重安全事故。2.3 版本号与清单的对应关系排查版本号的匹配逻辑也容易出坑。项目里常见做法是启动时请求version.json返回remoteVersion和remoteManifestUrl。客户端拿本地版本号和远程版本号做比较决定是否需要更新。这一步比较的时候我建议统一用整数版本号而不是字符串。字符串比较在版本号超过两位数时会出现“v100小于v99”之类的低级错误。还有个容易被忽略的点版本号接口本身也建议做缓存穿透保护。CDN对版本接口配置了强缓存的话客户端永远拿不到最新版本号。我排查过一个线上问题版本接口在CDN上缓存了10分钟导致发版后用户最长10分钟内无法触发更新后台看着用户全在线其实版本全是旧的。所以版本号接口在CDN上的Cache-Control建议设置为no-cache或者极短时间比如30秒。如果担心CDN节点回源压力大可以让源站做一次缓存但客户端侧的版本接口一定要保证新鲜度。2.4 清单差异对比的推荐实现客户端拿到新清单后需要和本地缓存的旧清单做差异对比决定哪些AB包需要下载。这个对比逻辑我推荐放在子线程里做避免阻塞主线程引起卡顿。对比的核心不是遍历所有AB包而是先比对hash字典。具体做法是将新旧清单中的AB包路径作为keyhash值作为value构建两个字典然后求差集。差集中的AB包就是待下载集合。如果AB包本身没有变化直接沿用本地文件不用重复下载。这里有个性能细节Manifest解析后依赖关系是树形结构但差异对比一定要把“依赖链上的变化包”也纳入待下载列表。A包依赖B包B包变了A包也必须重新下载否则加载A时引用旧依赖会出现资源错乱。我实际排查中见过只更新了单个资源包忘了更新其依赖链导致UI贴图错位的问题就是因为差异对比时没有扩散依赖关系。3. 下载过程中的CDN链路与传输安全3.1 CDN缓存策略对热更新的影响CDN是热更新最依赖的传输层但也是排查中最让人头疼的一环。最常见的坑是AB包上传到CDN后CDN节点没有回源更新导致不同地区用户拿到不同版本资源。要解决这个问题不能只靠上传文件还得主动刷新CDN缓存或者用带版本号的目录隔离。我推荐使用版本号目录隔离的方式。简单说每次发版资源都上传到一个全新的路径下比如/assetbundles/v103/。这样CDN的旧缓存路径里没有新文件客户端访问新路径时必然回源不会命中旧缓存。这种做法的代价是存储空间稍大一点但换来的是更新流程的确定性和安全性很划算。如果项目因为某种原因无法使用版本目录必须覆盖式更新那么每次发版后都要记得调用CDN的API做目录刷新。我踩过坑有一次忘了刷CDN缓存测试同学改了AB包重传结果还是旧资源排查到深夜才发现是CDN缓存没刷新这种情况其实很常见。3.2 HTTPS与明文传输的安全隐患资源传输走HTTPS还是HTTP在这条链路上差别很大。HTTP明文传输意味着中间节点可以看到资源内容可以篡改后转发客户端收到的AB包是否完整、是否被注入恶意代码完全没有保障。热更新资源本质上是可执行代码逻辑的一部分比如Lua脚本、AssetBundle里的预制体一旦被篡改后果很严重。所以排查的第一要求就是AB包下载和清单获取必须走HTTPS。市面上所有正规CDN都支持免费HTTPS证书这一步的成本极低但收益很大。如果项目还停留在HTTP建议把升级HTTPS作为热更新安全改造的第一步没有商量的余地。3.3 下载中断、重试与断点续传AB包下载过程中移动网络切换、弱网、后台切换都可能中断。如果下载中断后直接放弃用户会反复下载同一个大包体验很差。更严重的情况是下载中断后文件不完整但客户端没做完整性校验照样放行写入缓存之后加载时就会出现损坏资源的表现。我给项目做排查时要求AB下载模块必须满足三个条件支持断点续传记录已下载字节数下载完成后校验文件大小和hash核对无误才写入缓存如果校验失败删除临时文件重新下载而不是直接覆盖。断点续传的实现依赖HTTP Range头。下载前先请求文件元数据拿到总大小然后从本地临时文件的当前大小开始请求剩余部分。UnityWebRequest的SetRequestHeader(Range, $bytes{start}-)字段就是干这个的。实测在弱网环境下断点续传能减少大量重复流量尤其是那种上百MB的场景包效果非常明显。3.4 下载超时与重试策略的合理参数下载重试是个双刃剑。重试太频繁CDN压力大封IP风险高重试太少用户网络一抖动就失败体验差。我在项目中习惯用指数退避策略第一次失败后等2秒第二次等4秒第三次等8秒最多重试3到5次。这个策略的核心是不给CDN源站造成持续压力同时兼顾用户体验。超时设置也要分阶段看待。连接阶段TCP握手和TLS握手建议超时设置在10到15秒数据读取阶段建议每30秒检查一次是否有数据流动。如果30秒内没有任何字节到达说明连接可能已死需要触发重连或重试。我之前遇到过一个问题连接成功了但服务端一直没有返回数据如果只设置了总超时时间用户会一直卡在下载界面日志里什么都没有后来改成“读超时”才解决。超时参数这里给个我正常用的配置供参考DNS解析超时不单独设置跟随连接超时连接超时10秒读超时无数据空闲30秒最大重试次数3次重试间隔2秒、4秒、8秒4. 本地缓存安全与完整性核验4.1 本地缓存目录的正确选择Unity热更新资源的缓存目录常规做法是放在Application.persistentDataPath下。这个目录在不同平台上有不同的实际路径在Android上是/sdcard/Android/data/包名/files在iOS上是沙盒Documents目录。这个目录的优点是系统保证应用私有不需要额外权限卸载后自动清除不会污染用户设备。有些项目图省事把AB包直接放Application.temporaryCachePath。这个目录系统可能随时清理热跟新资源随时可能被清掉用户玩到一半资源丢失只能重新下载。我排查过的项目里有因为缓存目录选错导致资源反复下载的属于基础配置问题改进来也很容易。还有一点不要在代码里拼接绝对路径写死到外部存储。Android平台外部存储权限敏感而且不同厂商对权限的处理不一致容易触发崩溃或者适配问题。一切文件操作都走Unity的持久化目录API这是最稳妥的做法。4.2 本地缓存的写权限与进程安全本地缓存的写入操作要注意进程安全问题。同一时间只能有一个下载任务在写同一个缓存文件否则会互相覆盖产生损坏包。UnityWebRequest的downloadHandler是异步回调多任务并发下载时回调里的文件写操作要加锁控制或者在状态机里严格管理单个文件的下载状态。我实际遇到过一个诡异问题两个AB包文件同时写同一个缓存路径结果加载时资源时对时不对。后来排查发现是下载调度器里同一个请求被重复加入下载队列触发了并发写同一文件。解决办法很简单下载开始前检查该文件是否已在下载列表或已存在于缓存中双重判断后再决定是否加入队列。4.3 缓存文件的有效性校验与哈希比对本地缓存的AB包不能默认它是安全完整的。文件的hash值必须和CDN清单里的hash一致才能被加载器使用。这个校验建议放在两个时机一是下载完成落盘时校验二是加载器读取前校验。第一个校验防下载损坏第二个校验防缓存被其他程序篡改或磁盘异常。有人担心hash校验会影响加载性能。实际测试中对单文件执行一次SHA1或MD5校验对象是几十MB的AB包耗时在几十毫秒到一两百毫秒之间。而AssetBundle.LoadFromFile本身加载就需要几十毫秒加上hash校验的代价完全可接受。但如果追求极致可以对AB包做分块hash校验只校验文件头、文件尾和中间固定位置的数据块能进一步降低耗时。4.4 缓存清理策略与防回滚措施本地缓存的清理策略不能写得太激进。最简单的做法是保留当前版本所需的所有AB包额外保留上一版本的所有AB包作为滚动回退。如果磁盘空间不够优先清理下载时间最早且不在当前清单中的资源。千万不要在启动时全量清理缓存目录一旦清理后下载失败用户连回退的机会都没有。防回滚是另一个安全点。CDN清单下发新版本后客户端要把本地缓存的旧版本号一并更新。如果本地版本号可以被外部改动攻击者就能降级版本强制客户端加载旧的、可能存在漏洞的资源。所以本地版本号建议不要明文存在可写目录文件中可以集成到本地配置类管理中读取时做合法性校验发现问题就重置为初始状态触发全量更新。我一般这样设计本地缓存目录结构persistentDataPath/ ├── hotupdate/ │ ├── version.dat // 本地版本号 │ ├── manifest.hash // 最近一次可用清单hash │ ├── bundles/ │ │ ├── 路径哈希名1.ab │ │ ├── 路径哈希名2.ab这里有个细节缓存文件命名不能用原始路径名因为原始路径含层级目录文件名还可能带特殊字符。我习惯用AB包的AssetBundle名做MD5得到32位小写哈希作为缓存文件名。这样既能保证唯一性也规避了文件名合法性校验问题。5. 实操排查流程从现象到根因的定位方法5.1 排查第一步确认用户实际版本与清单hash接到热更新问题反馈后不要直接看加载器代码。第一步先让现场的同学或者测试复现问题环境拿到用户当前本地版本号、CDN清单版本号、以及实际加载成功的AB包hash。这三个信息可以快速判定问题出在哪一层。对比逻辑其实很简单本地版本号和CDN版本号不一致说明客户端未触发更新逻辑版本号一致但加载内容异常说明下载或缓存层有问题版本号一致且本地hash正确但加载内容还是旧资源说明加载器或依赖解析有bug。很多时候问题会自动定位到具体层级。给用户设备打一个日志标记把版本信息输出到日志文件再回传是定位热更新问题最有效的手段。我这边排查时都会先让测试开日志没有日志的话很多现场没法复现效率至少慢一半。5.2 全链路日志埋点的最小方案热更新排查离不开日志。日志埋点不需要多复杂但关键节点必须有输出。我习惯在每个环节加一行结构化日志包含时间戳、当前版本号、目标版本号、关键hash值、结果状态。这样回传日志后很快就能还原出完整的更新过程。比如下载阶段我会输出开始下载、请求URL、文件大小、已下载字节数、校验hash、写入路径、校验结果。加载阶段输出请求加载AB包名、命中缓存路径、文件hash、加载耗时。这些日志看起来啰嗦但线上排查时就是定位神器。5.3 模拟弱网、篡改、缓存过期三类异常场景排查热更新安全问题时我一般会在测试环境里主动构造三类异常场景。弱网场景用网络工具限制带宽和丢包率验证断点续传、超时重试、损坏包重新下载是否符合预期。篡改场景手动修改本地缓存中的AB包文件或者修改CDN清单的hash值看客户端是否能够识别并拒绝加载。缓存过期场景在CDN上设置较短的缓存时间或者在版本目录上做覆盖更新看客户端是否会出现旧资源残留。这三类场景覆盖了从CDN清单到本地缓存的主要风险点。能在这三类场景下正常工作的热更新系统基本可以认为链路安全性和健壮性都比较过关。5.4 一份可用于排查记录的排查表格排查过程中我建议用表格记录每一步的结果便于复盘和交接。表格可以做成这样排查阶段检查项预期结果实际结果结论版本接口返回版本号位数整数字符串带v前缀有风险CDN清单hash字段缺失每个AB包均有hash部分缺失补全构建逻辑下载链路HTTPS配置全部走HTTPS混合HTTP修复协议本地缓存文件hash校验校验通过才加载未校验增加校验逻辑加载器依赖链扩散依赖变更自动更新未处理依赖修复依赖逻辑这个表格本身不复杂但每一条都对应着实际代码或配置的修改项。排查结束后表格留下的就是一份可执行的技术改造清单。6. 常见问题速查与实战配套建议6.1 典型故障现象与可能原因对照表我把实际排查中遇到的典型问题整理成了速查表方便遇到类似问题时直接对照节省定位时间故障现象可能原因排查建议用户版本是新的但加载旧资源CDN缓存旧文件检查版本目录隔离刷新CDN缓存加载AB包报错资源损坏下载中断未校验hash增加落盘前完整性校验部分用户卡在更新界面版本接口被CDN缓存版本接口禁用强缓存更新一次后反复更新本地清单未持久化将清单hash写入version.dat依赖资源错乱差异对比未扩散依赖链将依赖变更包纳入下载列表缓存目录写入失败目录路径不可写改用persistentDataPath这个表格里的每一条基本都对应我前面章节提到的排查点。真出了问题按表格逐条核对大概率能在半小时内找到根因。6.2 排查过程中最容易踩的坑排查热更新问题时有几个坑我自己反复踩过这里专门记一笔。第一个坑是只看客户端日志不看CDN日志。很多资源问题在CDN侧会有非常明确的线索比如回源比例、缓存命中率、404数量。客户端日志只能告诉你“加载失败”CDN日志能告诉你“哪个节点在什么时间返回了哪个文件”。配合两边日志查定位效率翻倍。第二个坑是忘记校验AB包的依赖hash。单体AB包hash对了但依赖的另一个AB包已经变更加载出来还是错的。差异对比时务必把依赖链上的变化包一并纳入下载列表这一点我在第三章和第五章都强调过。第三个坑是盲目清理本地缓存。有些同事遇到资源损坏问题第一反应是让用户清理缓存重新下载。如果是偶发问题这会掩盖真实缺陷比如下载中断、校验逻辑缺失。正确的做法是先定位根因修复代码缓存清理只作为兜底手段。6.3 给中小团队的热更新安全升级建议如果你的项目还在用比较朴素的AB更新方式也就是直接比较版本号、下载即用、不校验任何hash我个人建议按这个优先级推进改造第一步给清单文件加签名校验。这一步不需要改架构只是构建流程多生成一个签名文件客户端多一次验证。收益极高成本极低。第二步AB包下载完成后做hash校验。这一步能挡住绝大多数损坏包问题也是排查链路中最关键的防线。第三步CDN走版本目录隔离加HTTPS。配置工作不大但能彻底解决缓存旧资源和传输被篡改两大类问题。第四步本地缓存校验加防回滚。等前几步完成了再投入因为防回滚依赖清单hash和版本号管理的一致性。6.4 关于日志与监控的最后一件事热更新链路里日志和监控不是可选项是必需品。别等到线上出了问题再补日志那时你手里没有任何现场证据排查会很艰难。我从一个线上事故里学到的教训是版本对比结果、清单hash校验结果、每个AB包的下载状态这三类日志必须默认打开线上环境也保留。另外可以做一个简单的数据上报统计热更新成功率、平均下载耗时、待下载AB包数量、失败重试次数。这些数据平时看着不起眼一旦发版后出现问题它们能最快告诉你影响范围和分布情况。热更新安全排查这件事本质上不是等出了问题再去修而是把每条链路的可靠性做扎实让问题在发生前就被设计挡住。
