做Unity转微信小游戏的开发我最怕的不是编译报错而是发完新版本之后玩家打开小游戏看到的还是老一套。改个关卡数值、换张UI皮肤听起来是常规操作但在微信小游戏环境里“版本迭代”四个字背后藏着资源缓存过期这个绕不开的槛。代码包有缓存、CDN有缓存、Unity里的AssetBundle也有缓存任何一个环节没处理好“更新成功”就是一句空话。这篇文章就是来聊这个事的。我会把Unity转微信小游戏场景下缓存过期的成因拆开讲再给出一套从资源命名、版本配置到Unity构建管线的完整处理方案最后附上我实际踩过的坑和排查思路。适合正在被版本更新问题困扰的Unity程序、小游戏开发以及想从零搭一套可靠资源更新流程的团队参考。方案不需要额外引入重型框架普通项目直接能落地。1. 先搞清楚微信小游戏环境里“缓存”到底是怎么回事1.1 Unity转小游戏后资源加载链路发生了哪些变化在原生Unity里加载本地资源就是从StreamingAssets或AssetBundle文件路径读取“网络资源”一般是运行时通过UnityWebRequest下载后写到Application.persistentDataPath再交给Unity加载。这个过程完全可控因为文件系统是自己的什么时候更新、什么时候清掉都由代码说了算。但转成微信小游戏后情况就不一样了。Unity逻辑虽然还能保留但宿主变成了微信小游戏运行时。远程资源要经过微信平台分发的链路再经过CDN节点最后落到用户设备上。微信客户端对HTTP请求有自己的缓存策略Unity层面的Caching系统也会把下载过的AssetBundle缓存到小游戏可写的文件系统里。两层缓存叠在一起一旦资源URL没变化客户端就很容易拿旧文件当新文件用。从构建侧看Unity转微信小游戏通常会把构建产物整理后上传到服务器或者通过微信小游戏适配工具打成代码包。在这个过程里如果资源文件名一直是bundle1、bundle2这种固定名字那客户端只要命中过一次缓存后续迭代就非常容易读到旧文件。我在项目初期就踩过这个坑服务器上传了整整一天新资源测试机愣是纹丝不动最后查到头才发现Unity的Caching把旧bundle当成了“最新版”。缓存过期问题的本质不是文件没传上去而是同一个URL被缓存后客户端根本不会重新请求服务器。理解了这一点后面所有方案就都好聊了。1.2 三重缓存微信客户端、CDN、Unity本地Caching我建议团队调试时把微信小游戏的完整链路拆成三层缓存来看排查会快很多。第一层是微信客户端的资源缓存。微信小游戏加载远程资源时如果服务器返回了Cache-Control相关响应头微信客户端会按照规则缓存资源。代码包本身也有一份缓存发布新版本后如果不做处理部分用户扫码打开仍是旧代码包。第二层是CDN缓存。你把资源放到对象存储或CDN上CDN节点会根据源站的Cache-Control策略或默认规则缓存文件。发布新版本时如果CDN节点还没有回源同一个URL返回的就是旧文件用户访问到的自然也是老资源。这个问题的隐蔽性在于你在源站看文件是新的但用户命中的节点是旧的。第三层是Unity运行时自己的缓存。UnityWebRequest下载AssetBundle时如果启用了Caching可以避免重复下载微信小游戏环境下Unity适配层会把下载内容写到小游戏本地可写目录。只要bundle的URL或版本标识一直没有变化Unity就会直接走本地缓存相当于客户端内部再也看不到更新。我用表格把三种缓存放在一起对比团队内部排查时可以直接贴出来当速查卡用缓存类型存放位置触发条件更新失效方式微信客户端缓存小程序本机代码包/远程文件HTTP响应有缓存头微信缓存策略、清理小程序、重新拉包CDN缓存CDN边缘节点源站响应头和CDN配置决定缓存过期、手动刷新、URL变化Unity Caching小游戏本地文件系统bundle URL未变且可缓存清理本地文件、更换URL、清除缓存目录有段时间我排查测试机的缓存问题发现单纯关掉开发者工具的缓存没有用就是这个原因。开发者工具的HTTP缓存关了但Unity的Caching还留着旧bundle或者CDN节点缓存没刷新开发工具里看得清清楚楚真机上却始终是旧版本。1.3 为什么不能靠“让用户清缓存”来解决很多项目出问题后的第一反应是让用户删除小程序、清理缓存然后重新进。这个思路只能临时缓解不能作为日常迭代的兜底。你不可能让每个玩家都去设置里找清理入口微信侧对小程序的缓存清理有粒度限制普通用户不一定能找到对应入口一旦用户量大售后成本根本扛不住。更麻烦的是即使清掉了微信HTTP缓存Unity的本地AssetBundle缓存不一定会被一起清掉下次加载可能还是旧内容。尤其在高版本微信上应用进程和文件缓存的管理越来越黑盒我们开发者能拿到的手段并不多。强行引导用户清缓存还容易带来一种“这个游戏是不是有问题”的负面体验。所以版本迭代时的资源缓存过期必须从资源消费侧设计上解决。核心思路一句话让每个版本的资源URL都保持唯一同时给版本配置一个“不能被缓存”的加载入口。后面所有方案都是围绕这句话展开的。2. 方案设计让资源URL永远指向唯一版本2.1 核心思路URL带内容hash旧缓存自然失效要解决缓存这里有个很朴素的原则一旦文件内容变化它的URL也变化。这样无论哪一层缓存命中过旧URL都不会再被用到因为新版本用的是另一个URL。具体做法是在构建Unity项目时对最终产出的AssetBundle资源做hash计算文件名从bundle_639c2.unity3d这样带上前几位hash。文件内容变了hash变了URL也变了。客户端重新拉取版本配置后用新URL下载新文件老的缓存文件留在设备上但永远不会被请求最多浪费一点磁盘空间不影响运行。这套思路和主流热更新框架里的“差异包hashing”思路是共通的只是在Unity转微信小游戏场景下我们控制不了代码包在微信侧发布的节奏但资源包的更新节奏完全由自己掌握所以更容易落地。需要注意的是hash只对“不会变”的文件有效。如果你有一个配置文件每次发布都更新但它又不带hash那就绝对不能开长缓存了这也是版本清单文件不能简单扔到静态CDN的原因。2.2 版本配置文件唯一的“允许变化”入口假设你有一堆带hash的资源包还需要一个小文件告诉客户端“这一版应该下载哪些资源”。这个文件就叫资源版本清单比如res_version.json。它的内容是当前版本号、资源列表、资源根路径等。它的作用就像收货地址变更通知别的快递箱都发往固定仓库了你要给用户送新货必须先把新地址告诉他。如果这个文件被缓存了整个更新就推不动。对这个文件正确的HTTP响应头是Cache-Control: no-cache或者max-age0, must-revalidate让微信和CDN都不能把它缓存太久。如果条件不允许修改CDN响应头就在请求URL后面拼一个每次发布都变化的参数比如res_version.json?v20250115但本质上还是需要动态生成入口否则参数自己也会被缓存。我比较推荐的方式是走一个后端接口去拿版本配置比如 /api/game/version接口内部返回当前最新版本号和资源清单。这样完全绕开静态文件缓存问题。但要注意接口本身要有兜底比如后端挂了能返回本地记录的旧版本让玩家至少能继续玩旧资源而不是直接白屏。这个兜底逻辑部分团队容易漏但线上故障里很大一部分就是这么来的。2.3 运行时更新流程启动拉配置按需下载整个流程可以这样拆玩家打开小游戏微信先加载代码包。代码包需要保证是新的这一步靠微信平台发布新版覆盖旧版。小游戏启动后先发起一个不可缓存的请求拿到res_version.json或者版本接口的数据。把返回的版本号与本地存储的res_version做对比。如果相同直接进入游戏加载本地已有的AssetBundle。如果不同解析版本清单里的资源列表对比本地缓存记录找出缺少或hash变化的bundle逐个下载。全部下载成功后把当前版本号记录到本地再加载游戏逻辑。下载失败的走重试或旧版本兜底。这个流程类似热更新框架的思路只是把更新目标从小游戏代码本身换成Unity资源包。在Unity转微信小游戏场景下代码包更新由微信平台管我们能管的主要是资源版本。把边界划清楚才不会出现在代码包里做热更新这种又累又不安全的事。2.4 为什么要用“版本号hash”而不是“时间戳”有些团队图省事把资源URL写成bundle_20250115.unity3d用日期当版本。短期能用但时间戳不等于内容标识。同一天内改了两次资源日期版本的URL还是没变客户端如果已经缓存了第一次的bundle第二次就拉不到新的。用内容hash则能准确区分内容是否真的变了。内容hash的计算可以在构建后或者上传前完成用MD5或SHA1都行作为文件名的一部分。需要注意文件名不宜太长微信小游戏对路径长度有限制取hash前8到12位足够碰撞概率在单项目规模下可以忽略。版本号则单独维护在res_version.json里用来确定“这一版整体是否变化”资源级的变化交给hash判断。两者配合才能既精准又简洁。3. 核心实操Unity构建管线与运行时更新改造3.1 构建侧打包后自动生成带hash的bundle和version清单建议在构建管线里完成这件事不要手动改名手动流程一定会漏。我这里用Unity的IPostprocessBuildWithReport接口写一个示例实际项目可以直接放到Editor目录下using System; using System.Collections.Generic; using System.IO; using System.Security.Cryptography; using UnityEditor; using UnityEditor.Build; using UnityEditor.Build.Reporting; using UnityEngine; public class BuildVersionWriter : IPostprocessBuildWithReport { public int callbackOrder 0; public void OnPostprocessBuild(BuildReport report) { // buildOutputPath 指小游戏构建产物的资源目录 string buildOutputPath Path.Combine(report.summary.outputPath, game-res); if (!Directory.Exists(buildOutputPath)) return; VersionManifest manifest new VersionManifest(); manifest.version DateTime.Now.ToString(yyyyMMddHHmmss); manifest.bundles new ListBundleItem(); foreach (string file in Directory.GetFiles(buildOutputPath, *.unity3d, SearchOption.AllDirectories)) { string hash GetFileHash(file); string fileName Path.GetFileNameWithoutExtension(file); string newName ${fileName}_{hash}.unity3d; string targetPath Path.Combine(Path.GetDirectoryName(file), newName); if (File.Exists(targetPath) false) { File.Move(file, targetPath); } manifest.bundles.Add(new BundleItem { name Path.GetFileName(targetPath), url $https://cdn.example.com/bundles/{Path.GetFileName(targetPath)}, hash hash }); } File.WriteAllText(Path.Combine(buildOutputPath, res_version.json), JsonUtility.ToJson(manifest, true)); // 这里可以把 res_version.json 和资源文件上传到发布服务器/CDN } private static string GetFileHash(string path) { using (MD5 md5 MD5.Create()) using (FileStream fs File.OpenRead(path)) { byte[] hashBytes md5.ComputeHash(fs); return BitConverter.ToString(hashBytes).Replace(-, ).Substring(0, 12); } } }注意我用的是文件整体MD5作为hash。文件改名后资源文件真实内容没变hash相同所以如果新旧文件内容一样hash不会误判成新资源内容变了hash才会变。这个环节的关键点是一定在Unity构建完成后、上传之前执行不能等上传到CDN再手动改。为了避免文件名太长hash只取12位一般规模的游戏资源碰撞概率远低于出一次线上事故的概率。代码里用JsonUtility是因为方便但JsonUtility对字典支持不好如果项目资源列表结构复杂建议换LitJson或Newtonsoft。版本清单的数据结构要提前设计好比如bundle的url、hash、依赖列表都要覆盖到。依赖列表尤其重要后面踩坑部分我会专门说。3.2 CDN与微信侧配置别让version文件也被缓存构建产物上传到CDN后需要确认两套响应头策略。一个Nginx配置示例location /cdn/bundles/ { # 带hash的资源缓存一年并且不可变 add_header Cache-Control public, max-age31536000, immutable; add_header Access-Control-Allow-Origin *; } location /cdn/config/ { # 版本清单不允许缓存 add_header Cache-Control no-cache, no-store, must-revalidate; }如果用的是腾讯云COS、阿里云OSS之类的对象存储通常在控制台或自有CDN域名规则里配置Cache-Control。部分平台对no-store支持不友好的话可以把规则配成过期时间为0效果也差不多。关键是把两类内容分开目录带hash的资源放bundles目录版本配置放config目录。甚至可以把版本配置放到一个独立的、不会被CDN默认缓存的路径下或者干脆通过后端接口返回。微信小游戏侧还有一个容易被忽略的点小游戏代码包本身在微信平台侧也有缓存。你通过微信平台发布新版本代码包后客户端不一定立刻拿到新包。资源方案做好后如果发现代码包逻辑没更新要去微信公众平台的“版本管理”看是否发布了新版。开发调试阶段在微信开发者工具里把缓存相关选项关掉能省很多排查时间。3.3 Unity运行时拉取版本并发起下载的示例在Unity小游戏适配的运行时启动流程通常在起主场景之前。我用一个协程来做逻辑很直接using System.Collections; using UnityEngine; using UnityEngine.Networking; using UnityEngine.SceneManagement; public class BootLoader : MonoBehaviour { [SerializeField] private string configUrl https://cdn.example.com/config/res_version.json; private void Start() { StartCoroutine(LoadLatestResources()); } private IEnumerator LoadLatestResources() { string localVersion PlayerPrefs.GetString(res_version, ); RemoteVersion remote; using (UnityWebRequest req UnityWebRequest.Get(configUrl)) { yield return req.SendWebRequest(); if (req.result ! UnityWebRequest.Result.Success) { // 拉不到配置尝试用本地版本启动 Debug.LogWarning(fetch version config failed: req.error); yield return LoadSceneFromLocal(); yield break; } remote JsonUtility.FromJsonRemoteVersion(req.downloadHandler.text); } if (remote.version localVersion) { yield return LoadSceneFromLocal(); yield break; } foreach (RemoteBundle bundle in remote.bundles) { bool needDownload IsBundleNeedDownload(bundle); if (needDownload) { yield return DownloadBundle(bundle); } } PlayerPrefs.SetString(res_version, remote.version); PlayerPrefs.Save(); yield return LoadSceneFromLocal(); } private IEnumerator LoadSceneFromLocal() { // 按项目实际情况加载主场景或本地bundle SceneManager.LoadSceneAsync(Main); yield break; } private bool IsBundleNeedDownload(RemoteBundle bundle) { // 根据本地已记录hash判断是否需要重新下载 string localHash PlayerPrefs.GetString(bundle_hash_ bundle.name, ); return localHash ! bundle.hash; } private IEnumerator DownloadBundle(RemoteBundle bundle) { // 下载完后记录hash并做完整性校验 yield break; } }核心不是代码多高级而是把“版本检查”和“资源加载”明确分开了。检查阶段只允许拿配置不加载任何可能过期的资源。下载阶段用bundle的URL和hash做差异判断本地存在相同hash文件就直接跳过不存在才下载。下载完再做一次hash校验防止CDN传输过程中文件损坏或回源到了旧版。这一步虽然多花一点时间但能避免太多隐性问题。实际项目里RemoteVersion、RemoteBundle这些数据类需要自己定义JsonUtility对字段名的命名处理也要提前约定好。我要特别提醒一下不要试图用UnityWebRequest在微信小游戏里直接写文件到任意路径微信小游戏环境下文件系统受限得依赖适配插件封装好的路径和接口。不同适配方案的接口名称略有差异但核心流程一致。3.4 兜底策略本地资源回退和“强制修复”入口线上环境总有网络抖动、CDN源站搬迁、后台误删文件等各种情况。资源更新不是永远顺利的。我的习惯是给下载bundle做三步兜底第一下载失败时立即重试两次每次间隔3秒以上。微信小游戏请求超时时间比较短最好在底层把timeout调大一点不然弱网下很容易一失败就回退。第二如果某个新bundle始终下载失败不打断启动流程而是回退到本地版本标记的旧资源启动。虽然功能可能不是最新的但至少玩家不会卡在白屏。这个回退逻辑要保证资源和代码匹配不然会出现资源新版、代码旧版互相不兼容的问题。第三做一个隐藏的“下载修复资源”入口放在设置页或异常检测逻辑里。玩家被某次更新弄崩后重新进入游戏能触发自动重置版本标记强制回到完整重下流程。入口可以放在一个小角落不必宣传但存在本身就能解决大量脏缓存问题。这些方案听起来多但实际代码量不大。必须重视的是“永远不要假设所有用户网络环境和设备状态都是好的”。微信小游戏面向的是各种中低端机型、老旧系统和弱网环境稍微宽容一点线上事故少很多。我现在每次发版前都会过一遍这套兜底确认不是只有“正常用户”能玩。4. 实战中踩过的坑与排查技巧4.1 最典型的五个缓存问题及处理对照表我整理一个速查表团队排查时可以先对照表定位一轮。现象大概率原因快速处理长期避坑更新后用户看到的还是旧UI/旧逻辑代码包缓存未刷微信平台新版没发布或客户端未拉新包去微信公众平台确认版本已发布用“检查更新”手动触发代码包也遵循版本发布流程灰度期别大意资源明明换了客户端还在用旧的CDN缓存或本地HTTP缓存未过期浏览器/开发者工具禁用缓存重试刷新CDN所有可变文件用hash化URL初次打开白屏控制台报不到资源version.json或接口被缓存拿到旧列表后下载失败清理微信缓存、重新进禁止缓存版本配置下载失败回退本地资源下载过但bundle加载报依赖缺失hash化后bundle的依赖链记录丢失检查AssetBundleManifest或加载顺序保持构建时的依赖清单更新时按顺序加载清掉微信缓存老问题依旧Unity Caching层旧bundle没被清删除本地文件或清缓存清理接口要同时作用到Unity的Caching缓存目录4.2 调试时怎么用微信开发者工具定位缓存问题打开微信开发者工具在Network面板里能直接看到资源请求的响应头和耗时。如果你怀疑版本配置被缓存了在面板里点开那个请求看响应头里的Cache-Control。如果显示max-age3600那问题就出在这了。把工具里的缓存相关选项按需关闭再重新编译小程序能快速区分是微信缓存问题还是Unity资源问题。真机调试和开发者工具的行为不完全一致尤其CDN节点的缓存状态。经验是先在开发者工具里关缓存验证代码逻辑再用一个真机配合远程调试确认如果开发者工具能拿到新资源真机拿不到优先考虑CDN节点缓存和微信客户端的HTTP缓存。真机上的Network日志可以通过微信开发者工具的调试器看到但是首次启动的资源请求会更快有时候还没等日志打出来就结束了这时候可以用“真机调试2.0”模式人为放慢。定位到具体是某一层缓存导致的之后再把对应用户的存储目录、本地文件列表导出来看。Unity Caching的文件在微信小游戏环境里一般落在用户可写目录下的Unity子目录通过远程调试的“文件”面板可以检查到旧bundle是否还在。只要把三层缓存逐层排除90%的缓存问题都能在半小时内定位。4.3 我在这套方案里反复踩过的三次坑第一次我图省事在代码包里手动改了一个版本号但没有任何资源URL改动。发布后测试那边一整天都在报告“资源没更新”。当时我先怀疑服务器上传漏了查完之后文件都在最后才发现是Unity的Caching把旧bundle缓存了URL没变它永远不下载新的。这个教训让我彻底放弃“改版本号但URL不变”的偷懒方案老老实实做文件名hash化。第二次我在开发时把version.json手动放到了CDN静态目录默认配置的缓存时间又比较长。发布当天老用户和新用户拿到的是两个版本的配置文件测试环境自己因为走了缓存一直以为线上正常。后来我把配置改到后端接口返回并在CDN上把config目录设置为不可缓存问题才彻底解决。这次之后我定了一条规矩凡是会影响资源加载的配置文件一律走动态接口绝不直接挂成普通静态文件。第三次是接手一个资源结构很乱的老项目资源都做了哈希但Unity的依赖加载清单没有跟着更新。每次强制更新后加载bundle时老是报某一个依赖找不到。当时花费不少时间才弄明白原因因为只有某个主bundle更新了它依赖的公共bundle没了版本清单里也没有依赖记录。后来我坚持把构建生成的AssetBundleManifest解析出来把主bundle和依赖bundle一起列进版本清单里下载时按依赖顺序加载这才消停。而且后来发现这类依赖问题在“清掉缓存后重新进入”的场景特别容易复现一定要在更新逻辑里带上依赖列表。4.4 如果还想更稳灰度发布与秒级回滚最后这套缓存方案的好处还在于发布和回滚都非常灵活。版本清单是唯一的入口做灰度只需要让部分用户拿到新版清单比如按用户ID哈希取模或者按微信openId的尾号分流。线上万一出了严重问题最坏情况就是让所有用户回到上一版的版本清单资源文件只要不硬删旧版本的hash资源仍然能访问就实现了秒级回滚。我没有建议各位把旧资源一直保留但至少保留最近两个版本的资源包。频繁迭代的项目构建产物都堆着会很占空间可以定期清理三个版本以前的文件。清理时注意检查版本清单是否还会引用到他们避免出现“新清单删了旧文件但灰度还没覆盖到的用户回退到旧版本后下载不到资源”这种连环坑。我在生产环境就亲眼见过一个项目因为清理资源不及时、新版本配置文件又指向了已删除的旧bundle导致一上午都在报资源404。我自己的体会是Unity转微信小游戏的项目缓存过期问题在整个迭代流程里就是个看不见的定时炸弹。不提前做方案测试或者线上用户总会帮你找出来提前做了URL hash加版本配置这套组合拳反而省心很多。最后分享一个我一直沿用的技巧执行版本检查时不要只比对版本号是否相等还让配置接口额外返回一个minLocalVersion字段用来标记最低可接受本地版本。如果本地版本低于这个值说明之前的差异更新已经不可信直接走全量下载而不是只下载差异文件。这个思路在几次事故中帮我挡掉了最脏的那类缓存残留写进方案后团队也再没被“版本一样但资源不对”的问题纠缠过。