Addressables构建全攻略：分组策略、热更新与CI/CD自动化实践

1. 构建前想清楚分组策略决定Bundle形态很多团队用Addressables踩的第一个坑就是以为装好包、把资源拖进Group就算接入完成了。等第一次正式构建完打开日志一看打出来的Bundle数量、大小、依赖关系完全不是预期再想回头调成本就高了。所以我习惯把构建这一章分成两层看第一层是分组设计第二层才是Build Script的执行。分组设计没定好后面所有流程都是在错误的地基上盖楼。1.1 分组为何是构建的最前端Addressables构建的本质是按Group来划分AssetBundle的。你在Addressables Groups窗口里看到的每一个Group最终会决定哪些资源被打进同一个Bundle、哪个Bundle放在本地还是远程、更新时哪个包会被整体替换。这里最核心的原理是Addressables并不直接管理单个资源文件它管理的是带Addressable地址的“资源条目”构建时根据Group的设置把这些条目聚合到Bundle里再生成Catalog索引。我见过不少团队把几十个Group建得乱七八糟一个场景的资源散在五个Group里一个材质被七个预制体引用结果构建出来的Bundle里全是重复AssetCDN存储翻了倍、加载时GPU内存飙高。这些都是分组策略偷懒导致的。分组这件事看起来是编辑器的拖拽操作实际上是在做“资源的依赖图设计”。所以第一步不是急着把资源拖进去而是在构建前把项目的资源形态摸清楚哪些是启动就必须有的哪些是进入某个玩法才加载的哪些是高频复用的公共资源。回答完这三个问题分组方案基本就自动化了。1.2 三种常见分组策略我总结下来绝大多数Unity项目尤其是中大型项目分组策略大致能分成三类你可以对号入座。第一类是“按功能模块分组”。比如UI、角色、场景、特效、音频各一大组再细分成登录界面、主城、战斗特效这类二级小Group。优势是逻辑清晰哪个模块更新打哪个包适合做版本迭代和热更新。劣势是要保证组间的依赖合理如果公共资源不单独拎出来很容易出现多个Group都打进了同一份贴图造成重复资源。第二类是“按加载时机分组”。把启动场景、全局UI、公共Shader和字体这类必备资源放进Always Loaded或者Local Group把后期关卡、活动资源放进Remote Group按需下载。这种策略对手游尤其友好可以让首包控制得很小玩家不用等整个内容下完才能进游戏。缺点是分得太碎会导致Bundle数量爆炸加载时的Http请求和AssetBundle依赖查找都会变慢。第三类是“按资源类型分组”。所有材质放一起、所有模型放一起、所有音频放一起。这种分组适合中小项目或者工具类应用配置简单但到了大型项目基本行不通因为实际加载的最小单元往往是“某个玩法下的一整套资源”按类型拆会让运行时的依赖链拉得很长。坦白说实践中大多数项目是混合策略公共资源单独拉一个组并设置为Cannot Change Post Release高频玩法资源按模块分Remote Group低频活动资源再单独分活动组。这个后面讲Content Update Restriction时还会细说。1.3 构建脚本选型Build Scripts之间的差别Addressables的构建行为不是写死的它由Build Script控制。打开Addressables Groups窗口点Build下拉菜单你会看到几种选项New Build、Update a Previous Build、Clear Build Cache等。New Build下面默认有两个ScriptDefault Build Script和Play Mode Scripts里那几个。Default Build Script是常规的完整构建它会重新分析所有资源依赖、重新生成Bundle和Catalog适合正式出包。Update a Previous Build则是增量更新它基于上一次构建的Catalog和Bundle只生成发生变更的资源内容是热更新流程的核心。另外还需要注意Simple Build Script这类自定义脚本社区里有很多扩展比如支持自定义压缩格式、加密Bundle、生成版本信息文件等。如果你的项目需要把构建产物跟自己的发布系统对接大概率要写一个自定义Build Script这个我在后面实操部分会给出一个可直接用的模板。选型的原则不复杂第一次接入、日常开发期用Default Build Script就够到了要发灰度、做线上热更的节点就必须把“完整构建增量更新”两套流程都跑通并配合CI/CD自动化否则人工执行几十个步骤迟早出错。2. 构建前必须做好的配置分组和脚本方案定了接下来要处理的是构建参数。这一层常常被忽视但出现问题时十有八九都是配置不对导致的。2.1 Profile本地、远程路径怎么设Addressables的构建输出路径不是写死的它是通过Profile来管理的。打开Window Asset Management Addressables Profiles你能看到Local、Remote这两类路径相关的变量。常用变量包括LocalBuildPath、LocalLoadPath、RemoteBuildPath、RemoteLoadPath。这里我给你的建议是LocalBuildPath和LocalLoadPath保持默认项目内路径RemoteBuildPath一定要设置成一个独立的、用于存放可上传资源文件的目录RemoteLoadPath则要填运行时下载资源的URL前缀也就是你CDN的地址。很多团队在这两个字段里直接填死一个绝对路径等换电脑、换CI机器就出各种问题所以强烈建议路径中使用变量拼接不要写死。另外注意Platform变量。Addressables构建时会在路径中加入平台名比如Android、StandaloneOSX保证不同平台产物不会互相覆盖。这个机制会延续到运行时加载路径所以不要为了省事把平台变量去掉。2.2 Content Update Restriction热更方案的分水岭这个选项在Group的Advanced Options里叫Content Update Restriction有两个值Can Change Post Release和Cannot Change Post Release。它是做热更新时必须理解的一个概念。先说结论公共资源、核心底层资源Shader、UI基础图集、通用工具类资源全都设成Cannot Change Post Release。这类资源一旦变更会导致大量Bundle连带失效设成可变更会带来灾难性的更新体积。而玩法内容、活动资源这类发布后大概率会改的资源设成Can Change Post Release。原理是这样的Cannot Change Post Release的资源在构建时会被标记为“静态资源”它们的Bundle被固定下来发布后更新时不会被重打。Can Change Post Release的资源更新时Addressables的Content Update流程会为它们生成新的Bundle玩家只下载这部分增量。如果不做这个区分哪怕你只改了一个UI按钮的贴图构建出来的更新包也可能包含上百MB的Bundle——因为依赖公共资源的包全都重建了。这里有个实操细节发布后如果确实改了Cannot Change Post Release组里的资源Addressables会警告你并且更新时这个资源的引用会变得非常麻烦。所以我的建议是宁可把“以后可能会改但不确定”的资源先放进Can Change Post Release也不要轻易把公共资源设为可变更——公共资源变更的成本是整个更新流程重新规划。2.3 构建前还要检查的SettingsAddressableAssetSettings这个总设置文件里有几个开关直接影响构建结果很多人一直没动过容易在某个版本升级后踩雷。第一个是Build Remote Catalog。如果你要做热更新这个必须勾选并且要设置一个远程Catalog路径。运行时才能拿到最新资源索引。只构建本地Catalog的话加载的一直是安装包里的老版本资源列表。第二个是Ignore Unsupported Files。建议打开避免Extract Assets时压缩格式不支持的音频文件报错或者某些特殊资源格式构建失败导致整个构建中断。打开后这些文件会被忽略但你要记得自己排查掉这些不支持的内容。第三个是Strip Unity Version从AssetBundle中移除。如果项目安全策略允许建议勾选能减少一点包体和信息泄露还能降低AB包的兼容性风险。第四个是资源压缩方式。在Profile里可以选LZ4和LZMA。LZ4压缩比低一点但加载解压快LZMA压缩比高但加载时全部解压耗内存。手游资源多、追求加载速度的场景建议用LZ4或者干脆不压缩把压缩留给CDN的后来就能走HTTP的Accept-Encoding资源。不要盲选LZMA加载卡顿会很难受。如果你在构建时发现日志里有奇怪的报错先别急着看代码打开这组Settings逐项检查一遍经常能解决一半的问题。3. 实操构建入口、命令行与CI/CD集成配置做完终于可以真正开始构建了。这一部分我会从手动构建讲到脚本化再到接入Jenkins给你一套可以直接复制的流程。3.1 编辑器手动构建最简单的方式是打开Addressables Groups窗口选择Build New Build Default Build Script。构建完成后日志会显示产物输出路径。默认情况下Local组产物在项目目录的Library/com.unity.addressables/aa/Android或对应平台目录下Remote组产物在你配置的RemoteBuildPath目录里。这个手动流程适合本地验证但不适合发版。我见过有团队每发一版都是某个同事手动点按钮、手动收集Remote产物、手动上传CDN最后再手动改版本号。这么搞一次两次还行一个月发几次版人就会崩。所以务必往下看把构建脚本化。需要说明的是如果构建中途报错比如资源依赖分析失败构建会停止但内存里可能残留上一次的Build Cache。这时候选择Build Clear Build Cache或者直接删除Library/PlayerScriptAssemblies里的缓存文件再重新构建。别问我是怎么知道这个坑的。3.2 自定义构建脚本在实际项目中我倾向于写一个Editor脚本把构建逻辑封装成菜单命令方便后续接CI。下面这段代码我一直在用放在Assets/Editor/AddressablesBuild.cs里即可。using System; using UnityEditor; using UnityEditor.AddressableAssets; using UnityEditor.AddressableAssets.Build; using UnityEditor.AddressableAssets.Settings; using UnityEditor.Build.Reporting; using UnityEngine; public static class AddressablesBuilder { public static void BuildAddressables(string buildScriptType, string profileName) { AddressableAssetSettings settings AddressableAssetSettingsDefaultObject.Settings; if (settings null) { Debug.LogError(AddressableAssetSettings not found, create it first.); return; } // 切换Profile bool profileExists false; foreach (var profile in settings.profileSettings.GetAllProfileNames()) { if (profile profileName) { profileExists true; break; } } if (profileExists) { string profileId settings.profileSettings.GetProfileId(profileName); settings.activeProfileId profileId; } else { Debug.LogWarning($Profile {profileName} not found, use default.); } // 通过反射或直接查找BuildScript var buildScript GetBuildScript(buildScriptType); if (buildScript null) { Debug.LogError($BuildScript {buildScriptType} not found.); return; } AddressableAssetSettings.BuildPlayerContent(out AddressablesPlayerBuildResult result); if (!string.IsNullOrEmpty(result.Error)) { Debug.LogError($Addressables build failed: {result.Error}); throw new Exception(Addressables build failed: result.Error); } Debug.Log($Addressables build success, duration: {result.Duration}s); } private static ScriptableObject GetBuildScript(string typeName) { var settings AddressableAssetSettingsDefaultObject.Settings; if (settings null) return null; foreach (var script in settings.DataBuilders) { if (script.GetType().Name typeName) return script; } return null; } [MenuItem(Build/Addressables/Build Default (Android))] public static void BuildAndroidDefault() { BuildAddressables(BuildScriptPackedMode, Android); } [MenuItem(Build/Addressables/Build Remote Update (Android))] public static void BuildAndroidUpdate() { BuildAddressables(BuildScriptPackedMode, AndroidUpdate); } }这段脚本的核心逻辑是加载AddressableAssetSettings按名字切换Profile然后调用AddressableAssetSettings.BuildPlayerContent()执行构建。注意这里的BuildPlayerContent和旧版的BuildScript.BuildPlayerContent()略有差异新版API更简洁但返回结果里只有Error和信息具体日志需要看控制台。如果你想在构建完Addressables后直接接着打Player包可以用BuildPipeline.BuildPlayer传入合适参数。注意执行顺序先构建Addressables再构建Player因为Player打包时会把Addressables的Catalog和初始化数据打进去。如果把顺序搞反启动时会报找不到Addressables初始化数据的错。3.3 接入Jenkins做自动构建代码写好后接Jenkins就简单了。Jenkins里配置一个执行Unity构建的步骤核心就是调用Unity编辑器命令行。#!/bin/bash UNITY_PATH/Applications/Unity/Hub/Editor/2022.3.10f1/Unity.app/Contents/MacOS/Unity PROJECT_PATH/path/to/your/unity/project LOG_FILE/path/to/logs/build_$(date %Y%m%d_%H%M%S).log $UNITY_PATH \ -batchmode \ -nographics \ -quit \ -projectPath $PROJECT_PATH \ -executeMethod BuildScript.BuildAndroidPlayer \ -logFile $LOG_FILE EXIT_CODE$? if [ $EXIT_CODE -ne 0 ]; then echo Unity build failed, exit code $EXIT_CODE exit 1 fi echo Unity build succeed, log at $LOG_FILE这里有两个关键点。第一个是-executeMethod指向的方法必须是静态方法要写成类似BuildScript.BuildAndroidPlayer这样的全限定名并且这个类最好放在Editor目录下。第二个是-batchmode -nographics -quit这三个参数缺一不可否则Jenkins执行会强制打开Unity窗口或者命令不退出导致Job挂死。构建完产物怎么收集我一般会在构建脚本里把Remote产物的路径输出到一个固定文件Jenkins读取这个文件后用rsync或者ossutil、coscmd这类工具上传到CDN。下面是一个简单的上传片段以阿里云OSS为例ossutil cp -r $REMOTE_OUTPUT_DIR oss://your-bucket/addressables/ --update上传完之后Jenkins里再接一步“更新版本号”或“发通知”的步骤整个发版流程就自动起来了。注意一点Jenkins机器上的Unity环境要和本地保持一致包括同一Unity版本、同一组Addressables包版本否则不同机器构建出来Catalog和Bundle格式可能不一致正式版本会出现运行时加载不到资源的问题。3.4 微信小游戏等平台的特殊处理Unity做微信小游戏是另一个大热门Addressables构建在这个过程中需要额外几步处理这里单独拎出来说。微信小游戏运行时根本没有本地文件系统所有游戏安装包里的内容都会被转存到微信服务器远程资源则走CDN。Addressables的Local组产物在微信小游戏平台上会以“分包”或者“首包资源”的方式存在需要在小游戏适配插件里做处理。实操里我在微信小游戏平台通常把首包压到很小把大部分资源放到Remote Group同时确保RemoteLoadPath是HTTPS地址并且C#侧使用UnityWebRequest加载资源。如果遇到加载远程资源报跨域问题要在微信公众平台配置downloadFile合法域名否则构建好的Catalog和Bundle根本拉不到。另外微信小游戏包体有限制所以说到底你必须在Addressables里做好远程资源策略。我的习惯是把UI图集、Shader变体、音频这些体积大头都拆到Remote小游戏首包只保留启动场景、Loading界面和核心初始化代码依赖的资源。每次构建后检查Runner包大小如果超出限制先砍的永远是Remote Group覆盖范围而不是去压贴图。4. 构建高频问题排查实录这部分是我最有底气写的因为几乎每一个问题我都在项目里踩过有的还踩了不止一次。给你一份排查速查表遇到问题先对号入座。现象大概率原因解决方向构建失败报循环依赖或分析超时资源依赖关系有环或某个资源引用链极深用Addressables Analyze工具检查依赖图拆掉循环引用构建成功但运行时某资源加载不到Catalog版本与Bundle版本不一致清理本地CDN缓存重新完整构建并重新上传检查RemoteCatalog老玩家需要下载整个更新包分组时没有设置Cannot Change Post Release重新规划公共资源分组做Content Update Build构建很慢或内存暴涨资源冗余量大或Shader变体过多开启Build Cache使用Addressables的Build Layout报告查冗余远程资源加载报404RemoteLoadPath配置错误或CDN未同步核对Profile里的URL重新上传Remote产物后刷新CDNPlayer包打进Addressables后初始化报错Addressables先于Player构建或Catalog路径未生效调整构建顺序检查InitializeAsync的Remote Catalog地址4.1 循环依赖与重复资源报错里最常见的是“Circular dependency detected”或者构建日志里出现Asset Import异常。这种问题大部分不是Addressables引发的而是项目本身的资源依赖有环。比如A预制体引用了B组件B组件又引用回A预制体。正常Unity编辑器里不影响运行但Addressables在做依赖分析时就会卡住或者报错。排查方法打开Addressables的Analyze窗口Window Asset Management Addressables Analyze选择Check Scenes to Addressables Duplicated Dependencies和Check for Duplicate Assets这两项能快速找出重复引用。循环依赖的话配合Unity自带的Asset Dependency Viewer右键资源 Select Dependencies手工确认环在哪里然后把其中一个引用改成运行时获取而不是资源引用。4.2 构建成功但运行时加载失败实际中最隐蔽的问题是——本地构建验证一切正常发到线上就有资源404。我排查过多次最后定位原因是CI机器上构建的Remote产物没有真正上传到CDN对应目录或者上传后CDN缓存没刷新。尤其是用OSS/S3这类对象存储时如果上传时带了content-type不一致或者缓存头UnityWebRequest可能加载失败。另一个隐蔽原因是不同平台构建出来的Catalog是不通用的。你本地在Mac上构建了一套Android资源上传后没问题但它们的路径和Bundle格式与Windows上构建的不同。如果你的CI和本地开发机系统不一样构建出的产物别混用更不要手动把本地产物覆盖到CI产物目录中。4.3 老玩家不小心下载整个更新包这是热更新上线后最让团队肉疼的问题。表现为玩家更新一个几十KB的Activity资源的描述文件却提示要下载几百MB的更新。根本原因我刚才已经提过——公共资源或大依赖资源被设成了Can Change Post Release。举个例子你的UI通用图集被多个玩法界面引用如果你没有把它单独分离出来并设为Cannot Change Post Release那么任何引用这个图集的界面资源一旦修改构建Content Update时Addressables会把这个图集的Bundle和引用它的Bundle一起重新打包玩家就需要重新下载。另外构建更新时用错脚本也会出问题。很多人直接用New Build重新打一整套完整包然后上传覆盖远端CDN这样玩家侧的缓存匹配不到新Catalog就只能全部重下。正确做法是用Update a Previous Build基于上次发布版本的Build信息做增量并把更新的产物放到单独的Bucket路径下。4.4 构建速度太慢怎么办首次构建慢是正常的Addressables要对全部资源做依赖分析几千个资源花二十分钟不稀奇。但如果你每次构建都特别慢就要优化了。第一是资源数量资源数量动辄几万的工程构建性能瓶颈往往在AssetDatabase扫描阶段。这时候可以考虑把一些“分析完就不会变”的大资源锁定到Local Group减少每次全量扫描对象。第二是冗余资源。两张图片内容一样、只是大小或格式不同会被当作两个Asset打进不同Bundle里白白增加构建时间和包体。这个用上面提到的Analyze的Duplicate Assets检查能查出一部分更彻底的是直接在资源导入阶段做规范从源头避免复制粘贴改个名就用的习惯。第三是开启Build Cache。Addressables的构建缓存会保留上一次的分析结果二次构建会快很多。但如果缓存损坏导致结果异常建议还是Clear Build Cache再重新构建别为了省时间背地里埋雷。4.5 用Profiler和Event Viewer定位运行时加载异常构建的问题很多时候要到运行时才暴露。Addressables提供了Event Viewer和Profiler窗口Window Asset Management Addressables Event Viewer可以实时查看资源加载请求、依赖加载顺序和耗时。我排查加载卡顿时一定会开Event Viewer勾选Instantiation和Loading选项那个列表里会显示每一个操作的状态。比如某个AssetBundle加载了但一直没释放说明引用计数没归零或者是事件顺序不对导致某些资源提前预加载。再配合Unity Profiler里的Memory分类能很快定位是哪个资源加载异常拖垮了帧率。另外要提一句构建完的日志一定要存好。Addressables构建日志里通常会记录Bundle大小、资源数量和构建耗时这些是判断分组是否健康的第一手数据。我每次发版后都会把这个日志归档到一个统一目录方便后续对照排查。我在实际项目里折腾Addressables构建这几年最大的体会就是构建这件事不能靠“一个人点一下按钮”来兜底它必须变成一套可重复、可追踪、可回滚的流程。把分组策略、Profile配置、构建脚本和CI/CD串起来之后发版就从“心惊胆战”变成了“一条命令的事”。如果你正打算把Addressables引入项目或者已经被构建问题折磨了好几天希望这篇里写的这些配置思路和排查路径能帮你少走几步弯路。