简介面向 Unity 开发者的运行时 3D 模型导入加载源码工程基于 TriLib 插件实现可在游戏或应用中动态选择 FBX、OBJ、GLTF2、STL、ZIP 等模型加载后在场景中实时预览与替换适合需要模型动态更新、关卡/场景编辑器或 AR/VR 可视化功能的项目。工程基于 Unity 2021.3.27 标准渲染管线编写使用 TriLib 2.3.7 版本并兼容 Standard、Universal、HDRP 等多种渲染管线Windows、Mac、Linux、UWP、Android、WebGL 平台均可接入。压缩包为 7z 格式共 879 个文件、26.37MB以 C# 脚本、插件 DLL、材质与 Shader、FBX 示例模型、Unity 场景及配置文件为主结构完整便于直接学习模型加载流程、UI 交互和渲染管线适配方式。已有 267 人学习下载适合具备一定 Unity/C# 基础、希望快速落地动态模型导入与替换功能的开发者。 做这类运行时加载的Unity3d项目最烦的就是编辑器里拖拽导入FBX那套经验完全失效。我去年接了一个工具向的工程核心需求就是让用户在程序运行过程中自己导入外部3D模型当时在C#里选了TriLib插件来实现整套运行时3D模型导入加载功能从本地路径、服务器URL到拖拽文件全都走了一遍。这篇就把我的封装思路、核心代码和踩过的坑完整记录下来给同样在搞运行时模型加载的朋友一个能直接参考的底子。先说我为什么放弃Unity自带的Resources和AssetBundle方案Resources只能加载打进化包里的资源运行时根本读不到用户磁盘上的文件AssetBundle每换一次模型就得重新打一次包不适合偏工具型和沙盒型产品。TriLib这种第三方加载器虽然要付费但它是专门干这件事的支持FBX、OBJ、glTF、GLB、STL、PLY、3MF这些常见格式解析在子线程完成回调回主线程API设计得很顺手。你要做的其实不是“能不能加载”而是怎么把加载能力封装成稳定、可控、不泄漏内存的一套服务。1. 运行时加载3D模型的真实场景什么时候必须用它1.1 编辑器导入与运行时导入的本质差异在Unity编辑器里FBX模型是通过AssetImporter导入的Unity会帮你生成Mesh、Material、Avatar、AnimationClip这些资源跟随打包流程进入最终包体。但运行时加载是完全另一套逻辑程序已经打包发布用户在任意一台机器上拿到一个模型文件丢给你的程序你必须当场解析这个文件并创建出GameObject。两者最大的差异是——编辑器导入有Unity官方元数据支撑运行时导入完全依赖解析器自己。我那个项目最开始是让用户把SolidWorks导出的模型塞进场景做展示后来需求扩到了fbx、obj、gltf混着来。如果不借助TriLib这种成熟插件你等于要从FBX二进制解析开始写用C#手搓一个FBX解析器工作量堪比重新发明轮子。TriLib内部把格式解析和Unity对象创建隔离开解析文件在后台线程做创建GameObject、Mesh、Material这些Unity对象时自动切回主线程从设计上就绕开了Unity API不能在子线程调用的硬限制。1.2 Unity原生加载方案对比为什么TriLib是更优解方案能否加载外部文件支持格式是否需要打包流程运行时成本Resources.Load不能Unity原生资产必须打包低AssetBundle不能直接读磁盘自定义打包格式必须打包中UnityWebRequest 自写解析可以取决于自写解析器否极高TriLib可以FBX/OBJ/glTF/GLB/STL/PLY/3MF等否中等很多团队在做一个需要导入外部模型的需求时第一反应是“让用户把模型上传到服务器我们在后台转成AssetBundle再下发”。这种思路能跑通但延迟大还强制用户必须通过服务器中转对于纯本地工具类软件完全说不通。TriLib这种方案把加载过程放在客户端天然支持离线模型格式兼容性还比AssetBundle好——AssetBundle本身就是Unity私有格式TriLib加载的是行业通用格式用户用Blender、3ds Max、SolidWorks导出的原始文件就能直接用体验完全不一样。我建议下面这几类项目可以优先考虑TriLib而不是自研模型展示类工具、CAD/BIM预览软件、沙盒建造类游戏、自动化测试框架里需要动态换模型的地方。如果是做纯网游所有模型都由服务器分发那还是AssetBundle更合适。2. TriLib导入与前置配置版本、授权、文件访问权限2.1 版本选择和API风格差异TriLib目前市面上能搜到两类版本1.x老版本和2.x重写版。1.x的回调风格偏旧很多历史教程和论坛帖子都是1.x的写法比如AssetLoader.LoadModelFromFile这个API在1.x里并不存在或者参数顺序完全不同。我建议新项目一律用2.x因为2.x把加载入口收敛成AssetLoaderOptionsAssetLoader.LoadModel*静态方法代码可读性好很多。安装方式就是从Asset Store导入或者官网下载.unitypackage再Import。导入后如果工程报编译错误最常见的两个原因一是Scripting Runtime Version没升到.NET 4.x或.NET Standard 2.0TriLib用了一些较新的C#语法老版本的.NET 2.0 Subset编译不过去二是有其他插件和TriLib共用DLL导致冲突。第二个情况比较棘手我的建议是刚导入时先开一个纯净工程验证TriLib能编译再往主工程里合并这样排查冲突快很多。2.2 Player Settings里容易漏掉的打包配置运行时加载外部模型打包配置和编辑器里纯调API完全是两回事。我最先踩到的是打包后Android上读不了SD卡文件iOS上读不了Documents目录下的文件Windows桌面版倒是没这问题。TriLib开箱只帮你做文件读取和解析文件系统权限这个事得自己处理。Android平台必须在Manifest里声明READ_EXTERNAL_STORAGE权限iOS用Application.persistentDataPath绕过沙箱限制Windows桌面端反而是最省心的。还有一个打包后才会暴露的坑Shader Stripping。如果你的工程开启了Strip Engine CodeIL2CPP裁剪而TriLib加载的模型材质用到的Shader没有提前打进包运行时材质就会变成洋红色。解决办法是把可能用到的Shader加到Project Settings Graphics Always Included Shaders列表里或者是给Shader打上[Preserve]之类的标记。我在做glTF加载时被这个问题卡过一下午因为glTF的PBR材质映射到的Standard Shader在打包时被裁掉了。2.3 授权方式和商用边界TriLib不是免费插件但授权策略比较清晰个人开发者买一个License可以在多个自己名下的项目里用。需要注意的是如果你把TriLib封装成SDK再卖给其他公司要确认你买的授权是否允许分发Runtime代码。我去年差点犯这个错——准备把封装好的加载服务作为中间件交付给甲方仔细看了License后才改成只交付源码工程不交付预编译的TriLib DLL。具体条款以你购买时的版本为准这个一定不能拍脑袋。3. 本地文件加载的完整链路从文件选择器到场景GameObject3.1 运行时文件选择器怎么选Unity编辑器里有个EditorUtility.OpenFilePanel能用但它只在编辑器下有效打包后根本调不到。运行时弹文件选择框主流方案有三种Windows下用System.Windows.Forms.OpenFileDialog需要引入System.Windows.Forms程序集实测能用但UI风格和Unity游戏画面完全脱节偏桌面工具风。用Asset Store里的Runtime File Dialog插件UI是Unity绘制的可定制性强适合游戏内嵌界面。自己写一套文件浏览器工作量中等优点是完全贴合项目交互风格。我当时做的是工具类应用直接选Windows Forms方案代码最短。如果是游戏里给玩家用的还是建议用Unity UI做一套不然体验割裂。下面是Windows Forms方式的示例using System; using System.Windows.Forms; using UnityEngine; public static class RuntimeFileDialog { public static string ShowModelFileDialog() { using (OpenFileDialog dialog new OpenFileDialog()) { dialog.Filter 3D 模型文件|*.fbx;*.obj;*.gltf;*.glb;*.stl;*.ply;*.3mf; dialog.Multiselect false; dialog.RestoreDirectory true; if (dialog.ShowDialog() DialogResult.OK) { return dialog.FileName; } return null; } } }注意在Unity里直接调用WinForms时需要保证工程的Api Compatibility Level不是.NET Standard 2.0的子集否则编译会报System.Windows.Forms找不到。Windows桌面项目建议把Api Compatibility Level设为.NET Framework。3.2 核心加载API和AssetLoaderOptions参数解读拿到文件路径后加载本身非常简洁。我这里给你一个完整的加载方法用到了TriLib 2.x的AssetLoader.LoadModelFromFileusing TriLib; using TriLib.Interfaces; using TriLib.Utils; using UnityEngine; public class ModelLoader : MonoBehaviour { private AssetLoaderOptions _options; private void Awake() { _options AssetLoaderOptions.CreateInstance(); _options.AutoLoadMaterials true; _options.AutoLoadLightmaps false; _options.GenerateColliders false; _options.MarkAssetsLoadedAsLoadedByDefault false; _options.ImportBlendShapes true; _options.ImportMorphs true; } public void LoadFromFile(string filePath, Transform parent) { AssetLoader.LoadModelFromFile(filePath, _options, (AssetLoaderContext context) { GameObject loaded context.LoadedGameObject; if (loaded null) return; loaded.transform.SetParent(parent, false); loaded.transform.localPosition Vector3.zero; loaded.transform.localRotation Quaternion.identity; loaded.transform.localScale Vector3.one; // 这里可以做后处理比如生成Collider、设置Layer AttachMeshCollider(loaded); }, (AssetLoaderContext context, float progress) { Debug.Log($加载进度: {progress:P0}); }, (AssetLoaderContext context, IError error) { Debug.LogError($加载失败: {error}); }); } private void AttachMeshCollider(GameObject root) { foreach (var filter in root.GetComponentsInChildrenMeshFilter()) { if (filter.GetComponentMeshCollider() null) { filter.gameObject.AddComponentMeshCollider(); } } } }这里的几个关键参数展开说下AutoLoadMaterials如果模型文件同目录下有纹理贴图TriLib会自动找到并创建材质。但注意这个只在加载本地文件时有效从字节数组加载时纹理文件不在内存里AutoLoadMaterials是帮不上忙的。MarkAssetsLoadedAsLoadedByDefault它的作用是控制加载出来的Mesh、Material等资源是否被标记为“已加载”。如果你打算缓存模型模板建议设成false这样在卸载资源时更可控。GenerateColliders如果你用不到MeshCollider保持false可以省不少时间和内存。大模型生成Collider非常耗时我实测加载一个30万面的FBX时生成Collider硬生生多了近1秒。ImportBlendShapes和ImportMorphs处理带BlendShape的表情模型和Morph动画时打开。不过这俩默认值有些情况是关的需要你手动打开。3.3 异步加载与回调线程逻辑为什么UI不会卡死我刚才提到TriLib的解析是在子线程完成的。很多朋友第一次写异步回调时会担心“回调里访问Transform会不会线程不安全”这里明确一下AssetLoader.LoadModelFromFile传进去的三个回调成功、进度、失败一定是在主线程执行的TriLib内部用UnityMainThreadDispatcher帮你切换好了。游戏运行时在主线程直接操作GameObject完全没问题。这也是我敢在成功回调里直接SetParent、加Collider的原因。不过进度回调确实可能在短时间内频繁触发如果你在进度回调里直接更新UI Text会出现抢主线程的问题尤其大模型加载期间。我的经验是把进度值暂存到一个字段只有变化超过1%才刷新UI避免每帧更新。4. 网络URL与二进制数据加载突破本地文件限制的两种方式4.1 用UnityWebRequest下载到缓存再加载项目做到一半产品提了新需求用户要从服务器拉取模型。TriLib官方也有LoadModelFromUrl但我实测下来并不总省心遇到网络超时、重试、断点续传这些场景还是自己控制下载流程更可靠。我的方案是先用UnityWebRequest把文件下载到本地缓存目录然后再走LoadModelFromFile。using System.Collections; using System.IO; using UnityEngine; using UnityEngine.Networking; public class RemoteModelLoader : MonoBehaviour { public IEnumerator LoadFromUrl(string url, Transform parent) { using (UnityWebRequest request UnityWebRequest.Get(url)) { request.timeout 30; yield return request.SendWebRequest(); if (request.result ! UnityWebRequest.Result.Success) { Debug.LogError($下载失败: {request.error}); yield break; } byte[] data request.downloadHandler.data; string cachedPath Path.Combine(Application.persistentDataPath, cached_model.bin); File.WriteAllBytes(cachedPath, data); // 复用本地加载逻辑 GetComponentModelLoader().LoadFromFile(cachedPath, parent); } } }好处就一个字稳。模型下载完一次后下次再用时走本地缓存和网络完全解耦上传新版本模型时换URL即可。这种方案还能在下载阶段就用原生的UnityWebRequest处理HTTPS证书、断网重试等逻辑比把网络状态直接抛给TriLib更可控。4.2 从Byte数组加载并解析常见格式还有一种数据源是Byte数组从网络流、从加密包、从数据库BLOB字段里读出来的模型数据都是byte[]。TriLib提供了LoadModelFromBytes但这里有个必须注意的细节第二参数要传文件名后缀TriLib依赖扩展名判断格式。public void LoadFromBytes(byte[] modelBytes, string fileName) { AssetLoader.LoadModelFromBytes(modelBytes, fileName, _options, context { /* 同样处理 */ }, (context, progress) { /* 进度处理 */ }, (context, error) { /* 错误处理 */ }); }我遇到的情况是服务器返回的响应头里不带文件名得在客户端拼一个比如model_ System.DateTime.Now.Ticks .fbx。后缀传错就很折磨人比如数据明明是glTF但你传了.objTriLib会拿OBJ解析器去硬解成功率极低。如果你从URL里实在看不出格式可以先下载后探测文件头特征判断是FBX还是glTF还是OBJ再决定后缀这个方法在关键接口场景下能救你一命。4.3 拖拽加载桌面端一个容易忽略的便利功能桌面工具类应用里用户最自然的一个操作就是直接把模型文件拖进窗口。Unity UGUI本身没提供拖拽文件进入窗口的原生支持但Windows下可以通过接管消息循环来拿到文件路径或者在Windows Forms里托管Unity窗口实现拖拽。我的实现比较取巧在游戏窗口外层包一层WinForms容器设置AllowDrop true然后在DragEnter和DragDrop事件里读取e.Data.GetData(DataFormats.FileDrop)拿到文件路径后转给ModelLoader。整个过程不到一百行代码体验提升却非常明显用户不用再去点“浏览”按钮找文件了。5. 加载FBX时踩过的三个坑骨骼、材质、主线程卡死5.1 坑一FBX带骨骼但加载出来没有Animator怎么办我这个项目的模型大多是从外部DCC工具导出的FBX有些是带角色骨骼的。第一次实测的时候发现模型层级、骨骼Transform都导进来了但Animator组件压根没挂上或者挂上了也没有Avatar。查了TriLib的文档和论坛结论是TriLib主要负责把网格和材质加载出来Humanoid Avatar重定向信息不是FBX标准里一定有内容的它强依赖Unity的Avatar生成逻辑。FBX文件里如果有Unity自定义的Avatar配置TriLib会尝试读取如果纯粹是Maya/Max导出通常没有。我的处理是加载后手动检查并补一个Animator用在Generic模式或运行时生成Avatarvoid EnsureAnimator(GameObject root) { var animator root.GetComponentInChildrenAnimator(); if (animator null) { animator root.AddComponentAnimator(); } // 如果模型包含humanoid骨骼可以尝试生成Avatar if (animator.avatar null) { animator.avatar CreateAvatarFromBones(root); } }运行时生成Avatar是一个比较深的话题简单做法是用AvatarBuilder.BuildHumanAvatar配合骨骼映射。但骨骼命名不同时容易映射失败所以我的兜底方案是如果Build失败就退回Generic模式至少保证模型display正确。5.2 坑二材质变紫和贴图丢失的完整排查链路运行时加载出来的FBX材质变紫是最常见的现象。有一次我打包后测试模型贴图全部消失在编辑器里却一切正常。排查过程走了一遍很典型的链路先在编辑器里用TriLib加载同一个文件现象正常。这排除了模型自身贴图路径错误的问题。打包后再次去加载发现材质变紫。开始怀疑是Shader裁剪问题。打开Player Log日志看到Material ... has no shader之类的警告。去Graphics Always Included Shaders里把Standard、Standard (Specular setup)加进去重新打包问题解决。如果纹理贴图本身丢失多半是FBX旁边的贴图文件没被找到。TriLib加载本地文件时会按FBX记录的相对路径找纹理。如果用户把FBX拷走时没带上贴图文件夹就会贴图丢失。这个没法在代码层面完全解决只能力所能及地在UI里提示用户“请确认模型文件与贴图在同一目录”。另外从Byte数组加载时AutoLoadMaterials失效的问题我的解法是加载后用统一的材质覆盖整个模型省去贴图映射的麻烦也能避免Shader差异化导致的表现不一致。5.3 坑三大模型加载时卡死主线程进度条还救不了TriLib的解析在子线程但当模型网格数据量巨大时解析完成后创建Unity Mesh和Material对象的过程仍然要消耗大量主线程时间。我有个测试文件面数超过200万打开时Unity Editor直接白屏十几秒进度条卡住不动。原因是创建大量Unity原生对象时内存分配和引擎底层操作没法完全异步化。对于这种情况我的建议有三个层面从源头限制UI上给出面数上限提示或者在加载完成后检查顶点数超出阈值就提示用户简化模型。分批创建TriLib支持加载选项里设置一些后处理延迟但实际效果有限。更可靠的是加载完先隐藏模型用Loading画面过渡等成功回调执行完再显示。加载前用缩略图预览先用AssetPreview生成预览图让用户确认模型无误再真正加载减少无效加载次数。我从这个坑里得到一个经验运行时加载模型这个功能永远不要假设用户会传“合理大小”的文件。程序里必须设定保护阈值比如超过一定顶点数直接拒绝加载并给出明确提示而不是让用户等几分钟然后崩溃。6. 加载器上线的最后一步内存管理与重复加载优化6.1 反复加载同一模型为什么会内存爆炸如果用户反复点“导入模型”每次都新建Mesh、Material、TextureUnity不会自动帮你清理GC也管不了那些通过new Mesh()创建的引擎对象。我实测连续加载同一个200MB模型10次内存直接翻了十倍这是因为TriLib每次都会重新解析并创建一套全新的资源对象。先前的资源没有被销毁Resources.UnloadUnusedAssets()也不会主动清那些被C#对象引用的Mesh。这就要求我们设计一套模型缓存机制至少在“模板”层面做复用。我实际用的结构是这样public class ModelCache { private Dictionarystring, GameObject _templateCache new Dictionarystring, GameObject(); public GameObject GetOrLoadTemplate(string filePath, Transform parent) { if (_templateCache.TryGetValue(filePath, out var template)) { return template; } // 调用TriLib异步加载 // 成功后存入_cache并返回加载出来的GameObject作为模板 return null; } public GameObject InstantiateModel(string filePath, Transform parent) { var template GetOrLoadTemplate(filePath, parent); if (template null) return null; return GameObject.Instantiate(template, parent); } }核心思路就是模板与实例分离。用户每次新开一个模型只是从模板Instantiate一份Mesh、Material、Texture这些大资源全部被模板持有每个文件在内存里只有一份。6.2 模板缓存和实例销毁的边界处理有缓存就必然要处理“什么时候清缓存”。我的经验是提供显式的“清空缓存”按钮用户在切换项目或打开新模型时触发Resources.UnloadUnusedAssets()。销毁模板前必须保证所有Instantiate出来的实例都被Destroy掉否则实例会引用已经被卸载的Mesh控台会刷Missing引用错误。如果用Resources.UnloadUnusedAssets()卸载外部加载的模型资源要注意它只对“不再被任何C#对象引用”的资源生效。所以模板一旦被缓存引用着就不会被卸载你必须在卸载前先从Dictionary里Remove掉。我最终做出来的ModelLoaderService是个单例对外暴露LoadFromFile、LoadFromBytes、LoadFromUrl、ClearCache四个方法。UI层只跟这个服务打交道完全不直接碰TriLibAPI。后边新增需求时比如想加个“模型最近使用列表”也只需要在服务层加内存和记录的逻辑UI和加载逻辑都不用动。6.3 网格合并与DrawCall优化加载完不是终点模型加载到场景里如果直接把FBX的整个层级结构原封不动交给玩家看有可能一个模型十来个MeshDrawCall直接爆掉。尤其CAD导出的模型零部件极多。我建议在加载成功回调里做一个可选的网格合并步骤把静态的、不动的模型合并成一个Mesh。void CombineMeshesOnRoot(GameObject root) { var filters root.GetComponentsInChildrenMeshFilter(); if (filters.Length 1) return; var combine new CombineInstance[filters.Length]; for (int i 0; i filters.Length; i) { combine[i].mesh filters[i].sharedMesh; combine[i].transform root.transform.worldToLocalMatrix * filters[i].transform.localToWorldMatrix; filters[i].gameObject.SetActive(false); } var finalFilter root.AddComponentMeshFilter(); finalFilter.sharedMesh new Mesh(); finalFilter.sharedMesh.CombineMeshes(combine, true, true); var renderer root.AddComponentMeshRenderer(); // 这里需要手动指定材质 }网格合并的代价是失去了子物体的独立性如果模型里有需要单独交互的零部件不能全班合并。所以我的方案是做成一个开关只在“纯展示模式”下启用。实操下来几十个零件的CAD模型合并后DrawCall降到个位数性能提升非常明显。说了这么多最后分享一个我自己的使用习惯如果你要把TriLib封进正式项目建议单独搞一个拆分包ModelLoaderService放在独立的程序集里里面不要混任何业务UI逻辑。这样以后升级TriLib版本时只需要替换加载层不用动业务代码。我在实际项目里用这个结构经历了TriLib小版本升级替换DLL后只改了几个配置字段业务层完全没受影响。这就是封装带来的安全感。本文还有配套的精品资源点击获取