简介：这份源码工程面向Unity开发者与AR/VR、游戏工具链方向的技术人员，解决运行时动态导入并预览3D模型的实际需求。工程基于TriLib 2.3.7插件，在Unity 2021.3.27与Standard Render Pipeline下实现选择模型、加载模型、场景预览的完整流程，可复用于关卡编辑器、模型替换、可视化展示等场景。压缩包共879个文件，约26.37MB，包含94个cs脚本、145个dll依赖库、18个shader与18个mat材质、13个unity场景、8个fbx示例模型及png、ttf、json等配套资源，覆盖代码、渲染与示例数据。已有270人学习。读者可获得可直接运行的工程结构、UI与加载逻辑代码、渲染管线导入配置说明，以及TriLib在SRP/HDRP/URP下的适配思路，便于快速搭建运行时模型导入功能并排查版本差异问题。
1. 运行时加载模型这件事，为什么值得单独开一个工程
做过 Unity 项目的人大概率都遇到过这个需求：用户想把自己手头的 3D 模型拖进应用里直接看，而不是每次都要重新打包一个 APK 或 EXE。这个需求在建筑可视化、工业巡检、教育课件、电商展示这几个方向里尤其常见。传统做法是把模型提前导入工程，做成 Prefab 或 AssetBundle，运行时只负责实例化。但这条路有个硬伤——模型必须提前进工程，用户没法自己带模型进来。
TriLib 这个插件解决的正是这个痛点：它把 FBX、OBJ、GLTF/GLB、STL、PLY 等常见格式的解析逻辑用纯 C# 重写了一遍，不依赖 Unity 编辑器的导入管线，所以能在运行时直接读文件、建网格、挂材质、生成 GameObject。换句话说，用户选一个模型文件，你的应用当场把它变成场景里的物体。
这篇笔记面向两类人：一类是刚接触运行时模型导入、想找一个能跑通的最小工程的开发者；另一类是用过 TriLib 但被材质丢失、内存暴涨、移动端崩溃折腾过的老手。我会从工程结构讲到参数配置，再到几个我踩过的坑，尽量让每一步都能照着复现。
2. 把 TriLib 接进 Unity 工程：目录结构、依赖与最小加载脚本
2.1 插件导入后的目录长什么样，哪些是必须保留的
TriLib 从 Asset Store 或官方渠道导入后，通常会在Assets/TriLib下展开。核心目录大致分这么几块：TriLibCore是运行时核心，包含所有格式的解析器和加载器；TriLibCore.Editor是编辑器扩展，负责导入设置面板；TriLibCore.Examples是官方示例场景；TriLibCore.Extensions放了一些辅助工具类。如果你只做运行时加载，TriLibCore和TriLibCore.Extensions是必须保留的，Examples可以在确认跑通后删掉以减小工程体积。
有一个容易被忽略的点：TriLib 依赖System.Runtime.CompilerServices.Unsafe和System.Buffers这类程序集，在 Unity 2020 之后的版本里通常由 Package Manager 自动处理，但如果你用的是较老的 Unity 版本或者手动拷贝 DLL，就要检查Plugins目录下有没有对应的托管库。缺了它们，编译期可能不报错，运行时一加载模型就抛TypeLoadException。
另外，TriLib 的异步加载依赖 Unity 的协程和AssetLoaderContext，这个上下文对象贯穿整个加载流程，后面调参数基本都在它身上。
2.2 一个能跑通的最小加载脚本
下面这段代码是我一般用来验证插件是否正常工作的最小脚本。挂在一个空 GameObject 上，运行时调用LoadModel并传入一个本地路径即可。
using UnityEngine; using TriLibCore; using TriLibCore.General; public class RuntimeModelLoader : MonoBehaviour { // 加载完成后生成的模型根节点 private GameObject _loadedModel; public void LoadModel(string filePath) { // 如果之前加载过，先销毁，避免场景里堆一堆模型 if (_loadedModel != null) { Destroy(_loadedModel); } // 配置加载参数 var options = AssetLoaderOptions.CreateInstance(); options.AutoAddColliders = false; // 按需开启，移动端建议关 options.UseUnityNativeTextureLoader = true; // 用 Unity 原生纹理加载，省内存 options.GenerateMeshColliders = false; // 大模型关掉，否则卡死 options.AnisotropicFilteringMode = AnisotropicFilteringMode.Disable; // 异步加载，回调里拿结果 AssetLoader.LoadModelFromFile( filePath, OnLoad, OnProgress, OnError, null, options ); } private void OnLoad(AssetLoaderContext context) { _loadedModel = context.RootGameObject; if (_loadedModel != null) { // 统一缩放到合适大小，避免模型过大或过小 _loadedModel.transform.localScale = Vector3.one; _loadedModel.transform.position = Vector3.zero; } } private void OnProgress(AssetLoaderContext context, float progress) { // progress 范围 0~1，可以驱动进度条 Debug.Log($"加载进度: {progress:P0}"); } private void OnError(IContextualizedError error) { Debug.LogError($"模型加载失败: {error.GetInnerException().Message}"); } }逻辑上分三步：先构造AssetLoaderOptions，这是所有加载行为的开关集合；再调AssetLoader.LoadModelFromFile，它内部会起一个协程，把文件读成字节流、按扩展名选解析器、逐块构建网格和材质；最后在回调里拿到context.RootGameObject，这就是模型在场景里的根节点。
参数说明几个关键的。AutoAddColliders控制是否自动给网格挂碰撞体，做展示类应用可以关，做交互拾取就得开。UseUnityNativeTextureLoader让纹理走 Unity 的Texture2D.LoadImage，比 TriLib 自带的解码器快，但只支持 PNG/JPG，遇到 TGA 或 DDS 还得回退。GenerateMeshColliders在模型面数超过十万时基本等于自杀，我一般只在需要精确碰撞的小模型上开。
2.3 文件路径怎么给：StreamingAssets、持久化目录与外部存储
路径是新手翻车最多的地方。TriLib 接受的是绝对路径或file://开头的 URI，不接受Assets/Resources那种虚拟路径。常见做法有三种。
第一种，把模型放进StreamingAssets，用Application.streamingAssetsPath拼路径。Android 上这个目录在 APK 内部，不能直接用File.ReadAllBytes，得先拷到持久化目录。第二种，让用户从系统文件选择器选，拿到真实路径后直接传给 TriLib，这是最灵活的方案。第三种，从网络下载到Application.persistentDataPath再加载，适合模型存在服务端的场景。
using System.IO; using UnityEngine; public static class ModelPathHelper { // 把 StreamingAssets 里的模型拷到持久化目录，返回可读路径 public static string PrepareStreamingAsset(string fileName) { string sourcePath = Path.Combine(Application.streamingAssetsPath, fileName); string destPath = Path.Combine(Application.persistentDataPath, fileName); // Android 上 StreamingAssets 不是普通文件，必须用 UnityWebRequest 读 #if UNITY_ANDROID && !UNITY_EDITOR var request = UnityEngine.Networking.UnityWebRequest.Get(sourcePath); request.SendWebRequest(); while (!request.isDone) { } File.WriteAllBytes(destPath, request.downloadHandler.data); #else if (!File.Exists(destPath)) { File.Copy(sourcePath, destPath, true); } #endif return destPath; } }这段代码的关键在于平台分支。编辑器里StreamingAssets就是普通目录，File.Copy直接能用；Android 上它是压缩包内的条目，必须走UnityWebRequest。iOS 上StreamingAssets同样是普通目录，但要注意文件是否被标记为可读。路径处理对了，后面加载基本不会出玄学问题。
3. 材质、贴图与坐标：让导入的模型看起来「对」
3.1 材质映射的三种模式与选择依据
TriLib 导入模型后，材质能不能正确显示，取决于模型文件里材质是怎么引用的。FBX 通常内嵌材质定义，贴图路径可能是相对路径；OBJ 配 MTL 文件，贴图靠 MTL 里的map_Kd指定；GLTF 则是 JSON 里写相对 URI。TriLib 提供了几种材质映射策略，在AssetLoaderOptions里通过MaterialMapper相关字段控制。
默认情况下，TriLib 会尝试用模型自带的材质参数创建 Standard Shader 材质。如果贴图找不到，材质会变成灰白色。我一般会显式指定一个MaterialMapper，把不支持的 Shader 映射到 URP 或 Built-in 的 Lit Shader 上。这一步在 URP 工程里尤其重要，因为 TriLib 默认生成的材质是 Built-in 管线的，直接用在 URP 场景里会显示成粉色。
using TriLibCore; using TriLibCore.Mappers; using UnityEngine; public static class MaterialSetup { public static AssetLoaderOptions CreateOptionsWithMapper() { var options = AssetLoaderOptions.CreateInstance(); // 创建一个自定义材质映射器 var mapper = ScriptableObject.CreateInstance<SimpleMaterialMapper>(); mapper.MaterialPreset = null; // 用默认 Standard options.MaterialMappers = new MaterialMapper[] { mapper }; // 贴图搜索路径，模型和贴图不在同一目录时很有用 options.ExternalResourceDownloader = null; options.TextureCompression = TextureCompression.Quality; return options; } }SimpleMaterialMapper是 TriLib 自带的轻量映射器，适合大多数场景。TextureCompression控制导入纹理的压缩质量，Quality会保留较高分辨率但内存占用大，移动端建议改成Normal或Fast。如果模型和贴图分开放，比如模型在models/而贴图在textures/，就需要自定义ExternalResourceDownloader或者提前把贴图路径重写。
3.2 坐标系与缩放：为什么模型导入后是躺着的
Unity 用的是左手坐标系，Y 轴向上；而很多建模软件导出时是 Z 轴向上，或者单位是厘米而不是米。TriLib 默认会做一次坐标转换，但转换规则取决于模型格式和导出设置。我遇到过最典型的情况是：一个在 Blender 里正常站立的模型，导入 Unity 后躺平了，原因是 FBX 导出时没勾选Apply Transform，或者轴设置成了Z Forward, Y Up之外的其他组合。
处理办法有两个。一是在AssetLoaderOptions里设置ConvertToLeftHanded = true，让 TriLib 自动做轴向翻转。二是加载完成后手动旋转根节点。
private void OnLoad(AssetLoaderContext context) { _loadedModel = context.RootGameObject; // 如果模型躺平，绕 X 轴转 -90 度 _loadedModel.transform.rotation = Quaternion.Euler(-90f, 0f, 0f); // 根据包围盒自动缩放到 1 米高 var renderers = _loadedModel.GetComponentsInChildren<Renderer>(); if (renderers.Length > 0) { Bounds bounds = renderers[0].bounds; foreach (var r in renderers) bounds.Encapsulate(r.bounds); float targetHeight = 1.0f; float scale = targetHeight / bounds.size.y; _loadedModel.transform.localScale = Vector3.one * scale; } }包围盒自动缩放是个实用技巧，尤其是用户上传的模型尺寸参差不齐时。bounds.Encapsulate把所有子渲染器的包围盒合并，再按目标高度算缩放系数。注意这一步要在模型实例化之后、任何物理操作之前做，否则碰撞体会按错误尺寸生成。
3.3 贴图加载失败时的排查顺序
贴图丢失是运行时导入里最高频的问题。排查顺序我一般这么走：先看模型文件同目录下有没有贴图文件，文件名大小写是否一致（Linux 和 Android 对大小写敏感）；再看 MTL 或 GLTF 里写的路径是相对还是绝对，相对路径是相对于模型文件还是工程根目录；最后看 TriLib 的日志，它会在 Console 里打印找不到的资源路径。
如果贴图确实存在但加载出来是纯色，大概率是纹理格式不被支持。TriLib 支持 PNG、JPG、BMP、TGA、DDS 等，但某些带特殊通道的 TGA 或 16 位 PNG 可能解码异常。这时候可以开options.UseUnityNativeTextureLoader = false，强制走 TriLib 自己的解码器试试。反过来，如果加载速度慢，就把它设成true，让 Unity 原生解码接管。
4. 性能与内存：大模型加载不崩的几条硬规矩
4.1 面数、纹理与内存的三角关系
一个 50MB 的 FBX，解压后网格顶点数据可能占 200MB 内存，纹理再占 100MB，加上 Unity 的托管堆开销，移动端 2GB 内存的设备很容易被系统杀掉。TriLib 在加载过程中会同时持有原始字节流、解析后的中间数据和最终的 Unity 对象，峰值内存通常是模型文件大小的 5 到 8 倍。
控制内存的手段有几个。第一，加载完成后立刻释放AssetLoaderContext里的原始数据，TriLib 提供了context.Dispose()或者让上下文自然回收。第二，纹理导入时降分辨率，options.TextureCompression设为Fast会生成较小的纹理。第三，对于超大模型，考虑分块加载或者只加载可见部分，但这需要改 TriLib 的解析逻辑，成本较高。
private void OnLoad(AssetLoaderContext context) { _loadedModel = context.RootGameObject; // 加载完成后释放上下文持有的原始数据 // 注意：RootGameObject 已经独立，释放上下文不影响场景对象 context.Dispose(); // 手动触发一次 GC，移动端大模型加载后建议做 System.GC.Collect(); Resources.UnloadUnusedAssets(); }context.Dispose()会释放文件流和中间缓存，但不会销毁已经生成的 GameObject。这一步在加载大模型后做，能明显降低常驻内存。Resources.UnloadUnusedAssets会清理没有引用的 Asset，配合 GC 一起用效果更好。注意不要在加载过程中调，否则可能把正在用的中间资源清掉。
4.2 异步加载与主线程卡顿的平衡
TriLib 的LoadModelFromFile是异步的，但网格构建和材质创建仍然在主线程完成。这意味着一个面数很高的模型，即使文件读取在后台线程，构建网格时还是会卡住主线程几百毫秒甚至几秒。如果应用对帧率敏感，比如 VR 或实时交互场景，这个卡顿是致命的。
缓解办法是分帧构建。TriLib 内部有TimeBudgetPerFrame之类的参数，控制每帧用于构建的时间上限。在AssetLoaderOptions里可以设置options.Timeout = 0表示不限制，但更好的做法是设一个合理的值，比如每帧 10 毫秒，让加载过程分散到多帧。
var options = AssetLoaderOptions.CreateInstance(); options.TimeBudgetPerFrame = 0.01f; // 每帧最多花 10ms 在模型构建上 options.MaximumLoadedTextures = 8; // 同时加载的纹理数量上限TimeBudgetPerFrame的单位是秒，设成 0.01 表示每帧最多 10 毫秒。这个值太小会导致加载时间变长，太大则卡顿明显。我一般根据目标帧率来定：60 帧的话，每帧预算 16 毫秒，留给模型构建的不要超过 8 毫秒。MaximumLoadedTextures限制并发纹理加载数，移动端设小一点能避免显存峰值过高。
4.3 移动端加载大模型的三个前置检查
在 Android 或 iOS 上跑运行时导入，打包前一定要确认三件事。第一，Player Settings里的Scripting Backend用 IL2CPP，Mono 在移动端对反射和动态代码支持有限，TriLib 的部分解析逻辑依赖反射。第二，Api Compatibility Level设为.NET Standard 2.1或.NET 4.x，太低会缺 API。第三，如果模型放在StreamingAssets，确认打包时没有被压缩，否则读取速度极慢。
另外，iOS 上要注意文件访问权限。如果模型从系统文件选择器选，需要NSDocumentsFolderUsageDescription之类的权限描述，否则应用会被系统拒绝访问。Android 11 之后对存储访问也有分区限制，用Application.persistentDataPath是最稳妥的，不需要额外权限。
5. 避坑与排查：那些让我加班到凌晨的加载问题
5.1 模型加载成功但场景里什么都看不到
现象：回调正常触发，context.RootGameObject不为空，但场景里就是没有模型。
原因通常有三个。一是模型被加载到了相机视野外，或者缩放比例极小（比如 0.001），肉眼看不见。二是材质的 Shader 不兼容当前渲染管线，模型其实在，但渲染成了透明或粉色。三是模型的 Layer 被设成了相机不渲染的层。
解决：先打印_loadedModel.transform.position和localScale，确认数值合理。再把相机对准模型包围盒中心，或者直接调SceneView的FrameSelected。如果是 Shader 问题，检查当前管线，把材质换成对应的 Lit Shader。Layer 问题用gameObject.layer = LayerMask.NameToLayer("Default")强制改回来。
5.2 加载到一半报 OutOfMemoryException
现象：大模型加载到 70% 左右崩溃，日志显示内存分配失败。
原因：TriLib 在解析阶段会同时持有原始字节、解析后的顶点数组和 Unity 的 Mesh 对象，峰值内存是文件大小的数倍。移动端尤其容易触发。
解决：先降纹理质量，TextureCompression设为Fast。再限制并发纹理数，MaximumLoadedTextures设成 4 或更小。如果还不行，考虑在加载前调Resources.UnloadUnusedAssets清一遍内存，加载后立刻context.Dispose()。实在太大的模型，只能做分块加载或者要求用户先压缩模型。
5.3 贴图在编辑器里正常，打包后丢失
现象：编辑器里模型贴图完整，打包成 APK 或 EXE 后贴图全白。
原因：贴图路径在打包后变了。编辑器里模型和贴图可能是相对路径，打包后StreamingAssets的结构和编辑器不一致，或者贴图没有被正确包含进包体。
解决：把模型和贴图放在同一个目录下，用相对路径引用。如果必须分开放，在加载前用ExternalResourceDownloader重写路径。另外确认贴图文件的Import Settings里没有勾选Exclude from build。Android 上还要注意StreamingAssets里的文件是否被压缩，压缩后的文件 TriLib 可能读不了。
5.4 同一个模型第二次加载时报错
现象：第一次加载正常，销毁后再加载同一个文件，报NullReferenceException或ObjectDisposedException。
原因：TriLib 的某些静态缓存或AssetLoaderContext在第一次加载后没有完全清理，第二次加载时引用了已释放的对象。
解决：确保每次加载都用新的AssetLoaderOptions实例，不要复用。加载完成后调context.Dispose()，但不要在回调外再访问context。如果用了自定义的MaterialMapper，确认它没有持有跨加载的状态。我一般会在加载前把上一次的_loadedModel置空并Destroy，再调Resources.UnloadUnusedAssets。
5.5 加载 GLTF 时动画不播放
现象：GLTF 模型加载后，网格和材质正常，但动画不动。
原因：TriLib 加载 GLTF 动画需要额外的AnimationClip映射，默认可能没有启用。另外，GLTF 的动画可能挂在子节点上，而Animator组件没有正确关联。
解决：在AssetLoaderOptions里确认options.AnimationType设为Generic或Humanoid，并检查context.RootGameObject上有没有Animator。如果没有，手动加一个，把加载出来的AnimationClip通过AnimatorController或PlayableGraph播放。GLTF 的动画采样率可能和 Unity 默认不同，必要时在导入设置里调整Animation Compression。
6. 进阶：把加载器做成可配置的运行时模块
走到这一步，基本功能已经跑通了。但如果你要把这个能力做成产品的一部分，就不能每次改参数都重新打包。我的做法是把AssetLoaderOptions里那些常用开关暴露成一个配置面板，运行时根据用户选择动态生成 options。
[System.Serializable] public class LoaderConfig { public bool autoColliders = false; public bool useNativeTextureLoader = true; public int maxTextures = 8; public float timeBudgetPerFrame = 0.01f; public TextureCompression textureCompression = TextureCompression.Normal; public AssetLoaderOptions ToOptions() { var options = AssetLoaderOptions.CreateInstance(); options.AutoAddColliders = autoColliders; options.UseUnityNativeTextureLoader = useNativeTextureLoader; options.MaximumLoadedTextures = maxTextures; options.TimeBudgetPerFrame = timeBudgetPerFrame; options.TextureCompression = textureCompression; return options; } }这个LoaderConfig可以序列化成 JSON 存在本地，也可以从服务端下发。用户改配置后，下次加载自动生效，不用重新发版。对于需要支持多种模型格式的场景，还可以按扩展名走不同的配置分支，比如 FBX 用一套参数，GLTF 用另一套。
验证加载是否成功，我一般会写一个简单的自检方法，在加载完成后检查网格数、材质数和纹理数，和预期对比。
private bool ValidateLoadedModel(GameObject model, int expectedMeshCount) { var meshFilters = model.GetComponentsInChildren<MeshFilter>(); var renderers = model.GetComponentsInChildren<Renderer>(); if (meshFilters.Length == 0) { Debug.LogError("模型没有网格，加载可能失败"); return false; } if (meshFilters.Length != expectedMeshCount) { Debug.LogWarning($"网格数不符：期望 {expectedMeshCount}，实际 {meshFilters.Length}"); } foreach (var r in renderers) { if (r.sharedMaterial == null || r.sharedMaterial.shader == null) { Debug.LogWarning($"材质缺失：{r.name}"); } } return true; }这个方法在自动化测试里特别有用。每次改完加载参数，跑一遍测试用例，确认网格数和材质数没有异常变化。比肉眼在场景里看靠谱得多。
最后说一个我自己的习惯：每次遇到加载问题，先把AssetLoaderOptions的所有字段打印一遍，确认没有意外的默认值覆盖了我的设置。TriLib 的默认值在不同版本间有过调整，升级插件后尤其要重新检查。这个习惯帮我省下了不少排查时间。希望帮到你。
本文还有配套的精品资源，点击获取
