Unity Addressable缓存路径自定义：彻底解决C盘空间不足问题

1. 为什么Addressable缓存会悄悄吃掉C盘空间1.1 默认缓存目录到底在哪Unity开发中Addressable Assets System以下简称Addressable是处理资源加载、打包、热更的常用方案。很多团队刚开始用Addressable时都挺开心资源管理确实方便按需加载、依赖自动处理、远程资源更新都省心不少。但用着用着就发现一个很现实的问题C盘空间莫名其妙就没了。第一次遇到这个问题时我翻遍了项目目录也没找到大文件最后用磁盘分析工具一扫发现一大堆资源缓存藏在系统盘里。Addressable的默认缓存路径是由Unity引擎底层AssetBundle缓存机制决定的在Windows上一般位于C:\Users\用户名\AppData\LocalLow\公司名\产品名\com.unity.addressables这里有个关键点路径中间的公司名和产品名来自Project Settings里的Company Name和Product Name。也就是说如果公司名和产品名没改过缓存会直接堆在默认位置而且每个项目各占一个独立目录。目录内部结构大致是这样的com.unity.addressables/ ├── data_0/ │ ├── 哈希值命名的bundle文件 │ └── 临时下载文件 ├── data_1/ ├── ... └── download/data_xx目录下存放的是已经下载到本地的AssetBundle文件文件名通常是一长串哈希值根本看不出是哪个资源。更麻烦的是Unity下载AssetBundle时会先写入download目录的临时文件校验Hash无误后才移动到正式缓存目录。这本来是防止下载损坏的安全机制但也会让磁盘瞬时占用翻倍一个1GB的bundle在下载过程中可能同时占用2GB空间。1.2 缓存无限膨胀的根本原因缓存目录越来越大一般不是单个资源体积惊人而是增量更新机制在反复积累旧版本。具体来说有这几个常见场景第一远程资源更新后旧版本的bundle不会自动删除。Addressable的缓存策略是新增存留不是替换清理。每次发版改了资源客户端下载新bundle后旧bundle依然躺在缓存目录里。如果一个项目迭代频繁几个月下来缓存体积轻松超过5GB。第二同一资源的多个变体都在缓存。Shader变体、纹理压缩格式ASTC、ETC2、DXT等、多语言本地化资源这些会被打在不同的bundle里但在缓存目录里全都以哈希文件名形式存在看不出对应关系不好手动清理。第三多个项目共用一台电脑时每个项目的缓存目录互相独立加起来就相当可观了。我见过团队里一台开发机上有七八个项目Addressable缓存加起来将近40GBC盘只剩几个GBUnity编辑器都开始报错。这些缓存之所以都堆在系统盘是因为Unity的Caching API在未指定路径时默认使用引擎提供的平台缓存位置。理解了这个机制自定义缓存路径的思路就很清晰了让引擎把缓存放到我们指定的目录去。2. 自定义缓存路径的核心原理与方案选型2.1 官方提供的Caching APIUnity从2019.3开始引入了Caching类的新API包括Caching.currentCacheForWriting和Caching.SetCurrentCacheForPlatform。这是实现自定义缓存路径最直接、最官方的方案。核心逻辑是通过Caching.SetCurrentCacheForPlatform(CacheTarget.Platform, cachePath)方法为当前运行的平台指定一个新的缓存根目录。传入的cachePath就是你想使用的路径比如D盘的某个目录。代码层面关键API是这样的using UnityEngine; public static class CachePathManager { public static bool SetCustomCachePath(string customPath) { if (!Directory.Exists(customPath)) { Directory.CreateDirectory(customPath); } bool success Caching.SetCurrentCacheForPlatform(CacheTarget.Platform, customPath); if (success) { var cache Caching.currentCacheForWriting; Debug.Log($已切换到缓存路径: {cache.path}); } else { Debug.LogError(缓存路径设置失败将使用默认路径); } return success; } }这里有几个细节需要注意。Caching.SetCurrentCacheForPlatform的返回值和路径是否合法、当前是否有正在进行的缓存读写有关。如果当前正好有AssetBundle正在下载或者缓存写入操作切换可能失败。所以最佳实践是在游戏启动最早期任何资源加载之前就调用。Caching.currentCacheForWriting是当前活跃的写缓存对象包含path、spaceOccupied、spaceFree等属性可以用它来查询当前缓存目录占用情况辅助做磁盘空间管理。2.2 各平台路径适配方案自定义缓存路径在不同平台上的策略完全不一样不能一套代码到处跑。Windows和macOS编辑器环境最直接直接传一个绝对路径就行比如E:/UnityCache/MyProject。但要注意路径中不能包含非法字符而且目标分区格式要支持大文件读写。实测NTFS格式下没有太大问题。Android平台上情况复杂很多。应用的外部存储目录分好几类Context.getExternalFilesDir()应用专属外部目录不需要额外权限但应用卸载时会一并删除Environment.getExternalStorageDirectory()SD卡根目录或内置存储根目录Android 11及以上访问受限/sdcard/Android/data/包名/外部应用专属目录同样不需要存储权限方案上我推荐优先考虑Context.getExternalFilesDir(UnityPlayer.currentActivity)因为这是Android官方推荐的存储位置既不需要申请存储权限又不会在卸载时留下垃圾文件。如果需要把缓存放在用户可见的公共目录比如用户自己选择路径那就需要考虑Android 11的分区存储限制常规做法是在Unity调用AndroidJavaObject来获取权限和路径。一个可用的Android路径获取代码大致这样using UnityEngine; public static class AndroidCachePathHelper { public static string GetExternalFilesDir() { using (var unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer)) { var activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); var context activity.CallAndroidJavaObject(getApplicationContext); var file context.CallAndroidJavaObject(getExternalFilesDir, null); var path file.Callstring(getAbsolutePath); return path /AddressableCache; } } }iOS平台的沙盒机制比较严格应用能自由读写的只有自己的沙盒目录。做法通常是拼接一个子目录比如Application.persistentDataPath /AddressableCacheApplication.persistentDataPath在iOS上对应的是Library/Application Support目录这个目录会被iCloud备份。如果缓存体量很大可以在Project Settings里配置不使用iCloud备份或者干脆使用Application.temporaryCachePath对应的Caches目录这个目录不参与iCloud备份但系统清理时会优先清掉它。缓存资源本身可以二次下载用Caches也不算大问题。WebGL平台又是另一套逻辑。Addressable在WebGL上走的是浏览器端的IndexedDB通过UnityWebRequest下载的AssetBundle最终会写入浏览器的存储空间而不是Unity进程可以指定的文件系统路径。热词里提到的unity 发布 webgl 使用 idbfs 写入失败问题本质上就是这个机制在某些浏览器环境下存储配额不足、隐私模式限制导致的。这在第4节会展开讲。2.3 和YooAsset对比的选型思考说到资源管理方案很多团队会在Addressable和YooAsset之间做选择。YooAsset是开源社区里非常活跃的一套资源管理框架解决了Addressable早期版本里不少痛点比如缓存策略不够透明、自定义功能受限、社区反馈修复慢等。两者的缓存机制差异很大。Addressable的缓存由Unity引擎托管路径和清理策略的可控性始终有限YooAsset把缓存策略完全开放给开发者下载、校验、缓存、清理的每一个环节都可以自定义。所以在需要精细控制缓存目录、磁盘占用、下载队列的场景下YooAsset近期越来越受欢迎。不过我们这个主题的核心是Addressable路径自定义选择哪个资源管理系统是前置决策。如果已经深度使用了Addressable的远程加载和依赖分析能力完全没必要为了缓存路径这个单点问题整体迁移到YooAsset。用Caching API把路径自定义这件事解决掉是成本最低的路径。等以后如果对资源管理有更高的定制需求再考虑整体切换。两种方案的核心差异我用表格梳理一下对比项AddressableYooAsset缓存路径自定义通过Caching API有限度自定义完全自定义可任意指定目录缓存清理策略依赖引擎缓存管理可控性一般提供详细的缓存操作接口学习成本官方方案接入简单社区方案需要理解框架设计远程加载与依赖管理完备且持续迭代功能完整开源可深度定制适合场景团队已深度绑定Addressable从零开始或强定制需求3. 实操完整接入步骤与配置方法3.1 写一个健壮的缓存路径管理脚本直接贴一个我在项目中用过的完整脚本包含路径选择、目录创建、写入权限校验、旧缓存搬迁和失败回退需要的可以直接照着改。using System.IO; using UnityEngine; public static class CachePathManager { private const string CacheDirName AddressableCache; private static string _customCachePath; private static bool _isInitialized; public static string CustomCachePath { get { if (!_isInitialized) { Initialize(); } return _customCachePath; } } public static void Initialize() { // 优先从配置文件中读取路径没有则用平台默认推荐路径 _customCachePath PlayerPrefs.GetString(CustomCachePath, GetDefaultPathForPlatform()); _isInitialized true; } public static bool SwitchCachePath(string newPath) { if (string.IsNullOrEmpty(newPath)) { Debug.LogError(缓存路径不能为空); return false; } try { // 1. 创建目录不存在时才创建 if (!Directory.Exists(newPath)) { Directory.CreateDirectory(newPath); } // 2. 校验目录是否可写 string testFile Path.Combine(newPath, write_test.tmp); File.WriteAllText(testFile, test); File.Delete(testFile); // 3. 如果当前缓存路径和要切换的路径相同直接返回 var currentCache Caching.currentCacheForWriting; if (currentCache.path newPath) { Debug.Log($已经在目标缓存路径: {newPath}); return true; } // 4. 检查当前是否有正在写入的缓存 if (Caching.ready) { // 在无正在占用的窗口期切换 bool success Caching.SetCurrentCacheForPlatform(CacheTarget.Platform, newPath); if (success) { PlayerPrefs.SetString(CustomCachePath, newPath); PlayerPrefs.Save(); Debug.Log($缓存路径切换成功: {newPath}); return true; } Debug.LogError($缓存路径切换失败: {newPath}); return false; } Debug.LogWarning(Caching系统还未就绪缓存路径切换失败); return false; } catch (System.Exception e) { Debug.LogError($切换缓存路径时发生异常: {e.Message}); return false; } } private static string GetDefaultPathForPlatform() { string basePath; #if UNITY_EDITOR_WIN || UNITY_STANDALONE_WIN // 非C盘优先其次使用系统盘的用户目录 basePath GetFirstAvailableDrive(); #elif UNITY_ANDROID basePath AndroidCachePathHelper.GetExternalFilesDir(); #elif UNITY_IOS basePath Application.temporaryCachePath; #else basePath Application.persistentDataPath; #endif return Path.Combine(basePath, CacheDirName); } private static string GetFirstAvailableDrive() { // 在Windows上遍历D、E、F盘找到第一个剩余空间超过5GB的盘 var validDrives new[] { D:, E:, F:, G: }; foreach (var drive in validDrives) { var info new DriveInfo(drive); if (info.IsReady info.AvailableFreeSpace 5L * 1024 * 1024 * 1024) { return Path.Combine(info.RootDirectory.FullName, UnityCache); } } // 所有盘都不满足条件退回系统盘 return Path.Combine(Application.persistentDataPath, UnityCache); } }这段代码有几个设计思路值得说明用PlayerPrefs记住用户选择过的路径下次启动不用再选正式切换前先写一个临时文件并删除用来验证目录权限Caching.ready属性判断引擎缓存模块是否就绪避免在缓存系统还没准备好的时候强行切换Windows上优先选择非系统盘而且要求剩余空间大于5GB避免缓存写一半就满了的尴尬实际项目里还可以把路径选择做成启动界面上的一个设置项用固定中文界面让玩家或测试人员手动改缓存位置。这样即使C盘满了用户也能自己解决不用改代码重新打包。3.2 初始化调用时机与流程设计脚本写好了什么时候调用是个技术活。调用时机不对路径设置就是白做。核心原则只有一条在任何Addressable资源加载之前越早越好。最稳妥的做法是在游戏启动画面的脚本Awake里调用或者在AppDelegate里提前处理。一个典型的启动流程是这样的using UnityEngine; public class Bootstrap : MonoBehaviour { private void Awake() { // 1. 先设置缓存路径必须最先做 var cachePath CachePathManager.CustomCachePath; CachePathManager.SwitchCachePath(cachePath); // 2. 初始化Addressable UnityEngine.AddressableAssets.Addressables.InitializeAsync(); } }这里有个容易踩的坑如果项目里用了多个场景场景中如果有任何组件在OnEnable或OnDestroy里触发了Addressable加载那么缓存路径设置必须在第一个场景加载之前完成。操作顺序一旦反了等Addressable已经用默认路径创建了缓存文件再切换路径也不会迁移旧数据缓存依然残留在C盘。所以推荐把Bootstrap挂在一个独立的启动场景中这个场景不加载任何资源专门处理这些初始化逻辑加载完毕后再跳转正式场景。这个模式非常稳定。3.3 缓存迁移与清理策略路径切换成功后旧路径下已经存在的缓存文件并不会自动搬迁。如果C盘上已经有几十GB的缓存这些空间还是被占用着。处理旧缓存的方式有两种一种是直接删除旧缓存目录。适用于旧缓存全是过期版本、没有保留价值的场景。public static void ClearCacheAtPath(string cachePath) { if (Directory.Exists(cachePath)) { Directory.Delete(cachePath, true); Debug.Log($已删除旧缓存目录: {cachePath}); } }注意删除前要确保没有正在运行的下载任务。稳妥做法是等所有Addressable操作结束后再执行或者干脆在关闭游戏前执行。另一种是做一个启动时的缓存体检逻辑检查缓存目录总大小让用户决定是否清理。配合编辑器的MessageBox弹窗在PC应用上实现一下也是很快的。关于Addressable缓存目录本身实际上Addressables API里提供了清除缓存的入口本质上是调用Caching.ClearCache()。但Caching.ClearCache()只能清Unity引擎管理的缓存如果我们把路径切到了一个自定义目录这个API依然能处理该目录下的缓存内容。完整的清理代码如下public static void ClearAllCaches() { bool cleared Caching.ClearCache(); if (cleared) { Debug.Log(所有缓存已清除); } else { Debug.LogWarning(缓存清除失败可能仍有缓存正在使用); } }Caching.ClearCache()有两个问题要注意。第一它会把所有平台所有项目的缓存一并清掉不分项目。第二如果当前有资源正在从缓存加载这个方法会失效。实际操作中我一般把清理逻辑放在场景全退完之后或者在启动界面提供一个清理缓存按钮引导玩家在加载完场景之后再操作。3.4 为磁盘空间不足场景设计兜底策略光设置自定义路径还不够实际运行时还是要考虑磁盘空间耗尽的情况。我建议在缓存加载流程中加一个空间预检逻辑。假设你的资源包大小是200MB下载前检查磁盘剩余空间public static bool HasEnoughFreeSpace(string cachePath, long requiredSize) { DirectoryInfo directoryInfo new DirectoryInfo(cachePath); DriveInfo driveInfo new DriveInfo(directoryInfo.Root.FullName); return driveInfo.AvailableFreeSpace requiredSize 256 * 1024 * 1024; }预留在256MB的余量防止下载过程中出现临时文件、日志等额外占用空间导致写入失败。如果空间不足可以弹窗提示用户清理垃圾文件或更改缓存路径而不是让下载任务在写文件时才报错。项目里可以做一个缓存空间监控模块每30秒检测一次缓存目录的剩余空间低于阈值时就自动触发旧版本缓存清理逻辑。4. 常见问题与排查技巧实录4.1 路径设置没有生效这是最高频的问题。代码看起来没报错Caching.SetCurrentCacheForPlatform也返回了true但查看日志发现Addressable依然在往默认路径写文件。排查这个问题的思路分几步第一步确认调用时机。如果Addressable已经初始化完成底层缓存系统已经开始工作SwitchCachePath调用即使返回true可能也只影响后续新增的缓存已经写入的缓存文件不会迁移。最彻底的排查方法是在Bootstrap脚本中加日志确认SwitchCachePath先于Addressables.InitializeAsync执行。第二步确认传入的路径不是相对路径。Caching.SetCurrentCacheForPlatform要求绝对路径相对路径会被忽略或解析到奇怪的地方。代码里Debug.Log出来的自定义路径如果是相对的就需要用Path.GetFullPath处理。第三步确认当前平台枚举和实际平台一致。CacheTarget.Platform会根据运行平台自动选择但如果你在编辑器里跑的是Windows EditorCacheTarget.Platform会指向对应平台而编辑器本身的缓存路径有时候和实际设备不一致。特别是Android和iOS设备上编辑器测试通过不代表真机也通过真机环境要打真机包验证。4.2 Android上写外部存储失败Android平台路径设置不生效很大概率是权限或路径不可写的问题。普通应用写入Context.getExternalFilesDir()路径不需要存储权限。但如果你想自定义到公共存储目录比如/storage/emulated/0/Download那就必须处理Android 11以上的分区存储限制。Android 11及以上应用访问公共目录需要AndroidManifest里声明READ_EXTERNAL_STORAGE和WRITE_EXTERNAL_STORAGE并且通过设置页或文件管理器授权。Unity工程里修改AndroidManifest的路径在Assets/Plugins/Android/AndroidManifest.xml设置完记得重新构建。更稳妥的方案是完全放弃公共目录直接使用上述AndroidCachePathHelper里获取的应用专属外部目录。这个目录对用户来说不是直接可见的但确实在外部存储上不占用系统分区。对于缓存资源来说放这里没问题。调试Android路径问题时可以使用Android Debug Bridge来查看文件系统adb shell run-as 你的包名 ls -la /sdcard/Android/data/包名/files/AddressableCache如果run-as无法进入说明应用是以debuggable身份运行的。正式的release包无法通过run-as查看数据目录只能结合Unity日志或者把文件列表输出到日志来排查。4.3 WebGL发布后的IDBFS写入失败WebGL平台发布时遇到IDBFS写入失败是个经典问题。IDBFSIndexedDB File System是Unity WebGL为浏览器提供的一种虚拟文件系统Unity把AssetBundle缓存存储在浏览器的IndexedDB数据库里。写入失败的原因通常会围绕这三个点第一浏览器存储配额不足。浏览器对单个网站的存储空间有限制Chrome的默认策略会根据磁盘空间和使用率动态计算配额通常不会给出固定上限但一旦超额IndexedDB写入就会失败。解决办法是在游戏启动时通过navigator.storage.estimate()检查剩余配额提示用户清理浏览器数据。navigator.storage.estimate().then(estimate { console.log(已用配额:, estimate.usage); console.log(总配额:, estimate.quota); });第二浏览器的隐私模式。Safari和Chrome的隐身模式下IndexedDB通常被禁止或限制Unity写IDBFS就会失败。这种场景除了提示用户换常规模式没有太好办法。第三用户清理浏览器缓存后游戏内缓存的资源包被清空。这本身不是错误但会导致游戏启动后重新下载资源。如果下载任务过大多做断点续传和加载进度展示同时把下载的临时文件管理好。对于WebGL场景Unity侧的缓存路径自定义动作基本是没有效果的。因为WebGL上不能用Caching.SetCurrentCacheForPlatform去指定浏览器文件系统路径。真正能控制的是在IndexedDB键名上做区分。Addressable在WebGL上的缓存键名是按应用信息生成的多项目部署在同一域名下时建议在发布设置里调整PlayerPrefs的保存位置或游戏标识避免多个游戏互相覆盖缓存。4.4 缓存目录占用空间诡异增长有时候设置了自定义路径磁盘空间还是在莫名其妙增长而且增长量明显大于下载的资源总量。这个问题通常不是缓存路径本身有问题而是有几个次要因素在叠加一是日志文件。Unity的logcat、Player.log、堆栈日志都会越积越大。特别是PC平台上调试版本会在应用目录下记录大量日志。排查时先检查Logs目录大小。二是资源校验的临时文件。Addressable下载时会在缓存目录下创建临时文件下载完成后改名。如果下载过程中断临时文件会残留。这类文件特征是文件名不像正式bundle那样规整或者零字节、超小尺寸。可以用脚本定期扫描缓存目录将所有未在缓存索引中登记的文件自动删除。三是AssetBundle的依赖资源重复打包。这个情况比较隐蔽。假设两个Group都引用了同一个材质且Group的打包设置没有把共用资源提取到公共bundle那么这个材质会被同时打进两个bundle。下载后两个bundle都保留在缓存里磁盘占用自然翻倍。排查方法还是用Addressables的Analyze工具检查打包结果里的资源重复情况这跟缓存路径本身无关但会直接影响缓存大小。我做过一个恶性案例一个模型资源被5个Group引用打包时候没开Dedupe结果缓存里同时存在5份几乎相同的bundle。修复做法是把公用资源单独放到一个Group打开Bundle Mode的Pack Together By Label并允许其他Group依赖它缓存体积一下就降了80%。4.5 部分资源加载后显示异常自定义缓存路径后有玩家反馈某些资源加载超级慢甚至加载失败但日志里没有明显报错。这通常是因为缓存切换后需要重新缓存所有远程资源首次进入时相当于没有缓存资源全部要重新下载图片加载速度当然会慢。若是重要资源频繁加载失败可能是切换路径代码和资源请求代码并发执行导致缓存读写冲突即Caching.SetCurrentCacheForPlatform执行时正好有资源在请求缓存。解决方式还是在加载所有资源前先完成切路径并且切路径时用一个标识量加锁加载系统发现标识存在就阻塞请求路径切换完成再放行。可以把切路径做成一个异步等待的方法public static async System.Threading.Tasks.Taskbool SwitchCachePathAsync(string newPath) { // 等待缓存系统就绪 while (!Caching.ready) { await System.Threading.Tasks.Task.Yield(); } return SwitchCachePath(newPath); }然后在Bootstrap里private async void Awake() { await CachePathManager.SwitchCachePathAsync(CachePathManager.CustomCachePath); UnityEngine.AddressableAssets.Addressables.InitializeAsync(); }切换完成后才初始化Addressable资源请求和缓存写入就不会打架了。5. 实用扩展结合构建流程做自动化缓存管理5.1 构建期自动修改缓存路径配置自定义缓存路径不只是在运行时做切换。对于PC游戏分发场景一个偷懒但很实用的策略是在构建时通过脚本生成一个配置文件把缓存路径预先设置好。Assets/Editor/CachePathBuildProcessor.csusing System.IO; using UnityEditor; using UnityEditor.Build; using UnityEditor.Build.Reporting; using UnityEngine; public class CachePathBuildProcessor : IPreprocessBuildWithReport { public int callbackOrder 0; public void OnPreprocessBuild(BuildReport report) { string configPath Path.Combine(Application.streamingAssetsPath, cache_path_config.txt); string defaultPath Path.Combine(D:/UnityCache, Application.productName); File.WriteAllText(configPath, defaultPath); AssetDatabase.Refresh(); } }这样构建出来的产物自带一个默认路径配置文件玩家运行游戏时选择使用默认缓存路径即可。如果有部分玩家的D盘也不存在逻辑会退回自动检测其他盘符或使用persistentDataPath兜底。这个机制特别适合面向普通玩家的PC单机游戏毕竟不是每个玩家都有能力自己改路径。5.2 自动化缓存统计与告警对长期运营的游戏来说缓存管理不能只靠玩家自觉。建议做一套缓存统计上报机制定期把以下信息上报到后台当前缓存路径缓存目录大小磁盘剩余空间缓存文件数量最近一次清理时间当磁盘剩余空间低于某个阈值或者缓存目录增长异常时后台可以推送通知方便运营配置针对性的清理引导弹窗。这个逻辑放在Unity侧就是几十行代码但能极大减少玩家因为磁盘空间不足导致的卸载流失。5.3 多项目共用缓存目录的隔离实践开发机上多个项目共用同一个缓存根目录时最好在根目录下按项目名分子目录避免互相干扰。可以定义一个通用工具脚本public static string GetCachePathForProject(string rootPath, string projectName) { return Path.Combine(rootPath, projectName, AddressableCache); }在项目开发阶段团队统一约定缓存根目录比如E:/UnityCache然后按项目名自动生成子目录。这样既能避免C盘爆炸又能让多个项目在一个开发机上和平共处。我在自己的开发机上就是这样配置的Addressable缓存从C盘挪到D盘后C盘可用空间一直很稳定再也没突然变红过。我在实际项目里踩过的坑还有不少但最值得说的一点是缓存路径自定义一定要在项目启动最早期处理并且要做好兜底策略这样才不会出现路径切了但缓存还在C盘的尴尬。如果你是刚接触Addressable建议先把基础配置、加载、打包流程跑通再来做缓存路径优化顺序反了容易被各种问题绕晕。对于已经上线的项目不用怕改动大缓存路径切换只涉及启动流程和一段脚本改动范围很可控早点做早点省心。