简介面向VR/AR开发者及Unity、Unreal Engine学习者的脚本案例文档围绕虚拟展览体验的搭建给出可扩展的开发流程框架。内容从项目文件夹创建、开发环境与SDK配置、分辨率与帧率设定讲起延伸到3D模型导入与多边形优化、场景布局、灯光材质调节以及头部追踪、手势识别等交互逻辑并覆盖UI界面、音效、构建发布、设备兼容性测试和后期维护。压缩包内共1个doc文件约21KB以流程说明和脚本框架为主体便于按模块查阅并二次修改。已有807人学习适合需要建立VR/AR项目全流程认知、对照检查工程环节或补充LOD、延迟加载等性能优化与排错思路的初中级开发者参考。1. 装 Unity 之前先想清楚VR/AR 虚拟展览这套环境的版本陷阱去年帮一个做展陈的团队搭虚拟展厅六个人折腾了三天最后卡住的原因不是脚本写错而是两台机器装的 Unity 版本差了半个小版本号导入的 XR 插件在另一台机器上死活认不到设备。这种 VR/AR 软件和插件的组合环境装的时候看着就是下一步下一步真跑起来才发现渲染管线、SDK、插件三者像齿轮一样咬着错一个齿就整条线停摆。这份 VR/AR 开发脚本案例走的是 Unity 或 Unreal 引擎 XR SDK/插件 3D 模型资源的典型路线最终产物是一个能头部追踪、手势交互、带 UI 和音效的虚拟展览应用。它适合两类人一类是要把线下展品搬进虚拟空间的开发者一类是刚接触 XR 想照着完整流程跑一遍的新手。装不好会怎样设备连上了但画面是黑的手柄能识别但射线点不到展品构建出来一装就崩——这些后面都会讲到。2. 环境准备Unity 版本、XR 插件与项目目录怎么定VR/AR 项目对环境的要求比普通 3D 项目苛刻因为多了一层「设备 SDK 必须和引擎版本对得上」的约束。这一章把装什么、装哪个版本、装在哪个路径讲清楚不然后面调参数全是白费。2.1 引擎版本选择LTS 优先别追最新Unity 选版本核心看两个数字大版本和 LTS 标记。LTS 是长期支持版XR 相关插件对它的适配最全。常见做法是选当前 LTS 里较新的一档而不是图新鲜上最新正式版——最新版往往要等 XR 插件跟上中间空窗期你就成了测试员。我一般会让整个团队锁死同一个版本包括补丁号。做法是在项目根目录之外单独建一个Environment.md记录# 环境锁定记录 - 引擎Unity LTS 版本团队统一补丁号一致 - XR 插件随引擎内置包管理器安装版本与引擎绑定 - 目标平台Android一体机/ WindowsPC VR - 渲染管线URP移动端优先 - 项目路径D:/Projects/vr_exhibition纯英文、无空格这里没有编造具体版本号因为真实项目应当以你当前引擎安装器里提供的 LTS 列表为准装上之后把实际版本号回填进这个文件。锁版本的意义在于XR 插件的很多行为差异是补丁级的团队里有人版本高一点就会出现「你那能跑我这不能跑」的经典扯皮。路径这条要单独强调。项目目录用纯英文、不带空格、不带中文深度控制在三层以内。Unity 在导入模型和构建时会产生大量临时路径中文路径在某些插件的中介脚本里会直接抛异常这个坑我踩过两次第二次是在构建阶段才炸排查了一下午。2.2 创建项目与安装 XR 插件项目创建时选 3D 模板URP 模板也可以但要在创建时就定下来中途换渲染管线会把材质全打回粉色。建好项目后按顺序做三件事装 XR 插件、开启 XR 支持、配置项目参数。# 目录结构建议在项目根目录下手动建立 vr_exhibition/ ├── Assets/ │ ├── Models/ # 3D 模型展品、展厅 │ ├── Materials/ # 材质球 │ ├── Scenes/ # 场景文件 │ ├── Scripts/ # C# 交互脚本 │ └── Audio/ # 背景音乐与环境音 ├── Packages/ # 插件清单需纳入版本管理 └── ProjectSettings/ # 项目配置同样要纳入版本管理Packages和ProjectSettings这两个目录一定要进版本管理。很多人只提交Assets结果同事拉下来发现插件没装、XR 设置是关的等于白拉。这份脚本案例里「项目初始化与配置」强调的配置开发环境落到操作上就是这两步包管理器里装 XR 插件包然后到项目设置里勾选启用。项目参数按目标设备定。分辨率常见 1920x1080 起步一体机设备要按它面板的物理分辨率来帧率这一项是 VR 体验的生命线移动端一体机至少锁 72fpsPC VR 往 90fps 走。低于这个数用户戴上头显十分钟就开始晕这不是优化问题是能不能用的问题。// Assets/Scripts/ProjectConfig.cs // 项目基础参数集中管理避免散落在各个脚本里 using UnityEngine; public class ProjectConfig : MonoBehaviour { // 目标帧率移动端一体机建议 72PC VR 建议 90 public int targetFrameRate 72; // 单眼渲染分辨率缩放1.0 为原生低于 1.0 降清晰度换帧率 public float renderScale 1.0f; void Awake() { // 关闭垂直同步VR 下由 XR 插件接管帧节奏 QualitySettings.vSyncCount 0; Application.targetFrameRate targetFrameRate; } }这段代码的意图是把帧率和渲染缩放做成可调字段而不是硬编码。vSyncCount 0是因为 VR 模式下帧同步由 XR 插件的时间步管理开着垂直同步反而会引入额外延迟。renderScale是性能不足时最先动的旋钮从 1.0 往 0.8 降清晰度损失换帧率稳定比砍模型面数见效快。2.3 设备 SDK 与插件接入这里就是关键词「vr ar 软件/插件」最集中的地方。接入顺序是先确认目标头显型号再装对应的 XR 插件包最后在项目设置里把插件注册进 XR 列表。常见的一体机走 Android 构建需要装 Android 构建支持模块和该设备厂商的 XR 插件PC VR 走 Windows 构建需要装桌面端 XR 运行时和对应插件。这一步最容易翻车的是构建支持模块没装全——包管理器里插件装着但点构建时提示找不到 Android SDK原因就是安装引擎时没勾对应平台模块得回安装器补装。提示设备 SDK 版本和头显固件版本也要对齐。头显那边升级了系统开发机上的插件没跟着升会出现设备能连、应用能装、但一进场景就黑屏的情况。3. 场景搭建与交互脚本模型导入、灯光材质与 C# 逻辑环境通了之后进入内容层。这份脚本案例的场景搭建和交互开发两块是真干活的部分参数和代码写错前两章的努力就白搭。3.1 模型导入与性能预算3D 模型格式优先 FBXOBJ 能用但对材质和动画支持弱。导入时不要无脑按默认设置导入面板里的几个开关直接决定后面跑不跑得动。导入设置项建议值原因Scale Factor1建模软件单位与引擎单位对齐一般是米Generate Colliders展品勾选展厅墙体勾选交互射线和物理碰撞要用Read/Write Enabled关闭开着会双倍占内存Mesh CompressionOff 或 Low压缩过头会让展品边缘出现破面Import BlendShapes关闭展览场景基本用不到省资源性能预算要提前定不要等跑不动再回头砍。移动端一体机单场景面数控制在 15 万三角面以内比较稳妥展厅墙体尽量用单面片配材质别用实心盒子模型。展品模型按重要度分级主展品给到几千面远景装饰物几百面即可。这份案例里提到「对模型进行必要的优化减少多边形数量」落到实处就是在建模软件里做减面导出前检查一遍不要指望引擎自动搞定。3.2 灯光与材质URP 下的取舍灯光是虚拟展览氛围的核心也是最吃性能的地方。URP 管线下一盏实时定向光加烘焙的混合方案最稳主光实时、环境光烘焙。烘焙Bake前把不动的物体标记为 Static生成光照贴图这样运行时几乎零开销。材质方面展品用 Lit 材质需要玻璃、亚克力效果的上 Transparent 模式并注意渲染顺序。有个细节常被忽略透明材质在 VR 双眼渲染下容易出现排序错乱单眼看着正常戴上头显一只眼睛能看到穿帮。规避办法是透明物体少用、面积控制小或者改用带 Alpha 裁剪的不透明材质。// Assets/Scripts/ExhibitHighlight.cs // 展品高亮用户指向展品时改变材质自发光强度 using UnityEngine; public class ExhibitHighlight : MonoBehaviour { [SerializeField] private Renderer targetRenderer; [SerializeField] private Color highlightColor Color.white; [SerializeField] private float highlightIntensity 0.6f; private Material mat; private Color originalEmission; void Start() { // 实例化材质避免修改共享材质污染其他展品 mat targetRenderer.material; originalEmission mat.GetColor(_EmissionColor); } public void SetHighlight(bool on) { if (on) { // 开启自发光关键词否则改颜色不生效 mat.EnableKeyword(_EMISSION); mat.SetColor(_EmissionColor, highlightColor * highlightIntensity); } else { mat.SetColor(_EmissionColor, originalEmission); } } }关键点在targetRenderer.material而不是sharedMaterial。前者会为这个对象创建材质副本改动只影响自己后者改的是所有引用同一材质的对象一不小心整个展厅的展品一起发光。_EMISSION关键词必须先开这是 URP 材质的一个常见盲点很多人只改颜色发现没反应就是漏了这行。3.3 交互逻辑头部追踪、手势与射线拾取这份案例里交互功能开发讲了头部追踪、手势识别两类。落到脚本层面头部追踪由 XR 插件自动接管相机你只需要把主相机挂上 XR 相机驱动组件手势识别依赖设备的输入系统射线拾取则要自己写。射线拾取是虚拟展览最核心的交互手柄或手部射线指向展品点击弹出详情。写的时候注意两件事一是射线长度要有上限二是拾取层要设 LayerMask 过滤别让射线打到地面和墙体上。// Assets/Scripts/RayInteractor.cs // 手柄射线拾取指向展品并触发高亮 using UnityEngine; using UnityEngine.XR.Interaction.Tools; public class RayInteractor : MonoBehaviour { [SerializeField] private XRRayInteractor rayInteractor; // 只拾取 Exhibit 层避免打到地面墙体 [SerializeField] private LayerMask exhibitLayer; [SerializeField] private float maxDistance 8f; void Update() { // 每帧检测射线命中的对象 if (rayInteractor.TryGetCurrent3DRaycastHit(out RaycastHit hit)) { if (hit.distance maxDistance) return; // 判断命中对象是否属于展品层 if (((1 hit.collider.gameObject.layer) exhibitLayer) ! 0) { var exhibit hit.collider.GetComponentExhibitHighlight(); if (exhibit ! null) exhibit.SetHighlight(true); } } } }LayerMask这段位运算看着别扭但它是 Unity 里判断层是否匹配的标准写法1 layer把层号转成位掩码再和配置的掩码做与运算。maxDistance限制射线长度是因为无限长射线会让用户觉得「隔空就能点」破坏空间感。一个高频翻车点是射线打不到展品模型导入了但没生成碰撞体或者展品不在 Exhibit 层。排查顺序就是先看 Collider 有没有再看 Layer 选没选对这两步能解决九成的「点不到」问题。3.4 UI 与音效别让界面浮在脸前UI 在 VR 里不能照搬平面思维。菜单挂载在 Canvas 上Canvas 的渲染模式设为 World Space尺寸压到实际空间中的合理大小摆在用户前方一米五左右、略低于视线的高度。挂太近会压迫太远会看不清字。音效这块背景音乐用 2D 音源保持恒定环境音效和展品提示音用 3D 音源配空间衰减用户走近展品声音才变大这是沉浸感最便宜的加分项。4. 构建部署与排错打包、设备测试和那些反复踩的坑脚本案例的发布部署和后期维护两块实际执行时坑最多。这一章把构建流程和常见故障合并处理。4.1 构建参数与设备安装构建前检查三处平台模块切到目标平台、XR 插件已启用、场景已加入构建列表。构建出来的包通过开发者模式装进设备装不上通常是签名或存储空间问题。构建项移动端一体机PC VR构建平台AndroidWindows纹理压缩ASTCDXT/BC图形 APIVulkan 优先DirectX最小 API 级别按设备固件要求不适用签名调试签名或自签无需额外签名纹理压缩选错会同时影响画质和内存ASTC 在移动端是当前主流别用 ETC2 凑合。图形 API 这一项有个实用建议Vulkan 性能通常更好但兼容性略差测试阶段如果遇到画面异常先切回 OpenGL ES 确认是不是 API 问题再决定最终用哪个。4.2 常见问题排查四条血泪记录现象一戴上头显进场景画面全黑但设备没断连。原因是相机没被 XR 系统接管或者主相机的位置被脚本改了。解决确认主相机挂了 XR 相机驱动组件检查项目设置里 XR 插件处于启用状态再把任何在Awake里修改相机transform的脚本逐个关掉测试。现象二手柄能识别但射线点不到任何展品。原因是模型没生成碰撞体或展品的 Layer 不在拾取掩码里。解决选中展品模型确认导入设置里勾了 Generate Colliders 或手动加了 Collider 组件再检查RayInteractor上配置的 LayerMask 是否包含展品所在层。这两项按顺序查能省一半时间。现象三构建成功安装到设备时提示解析包失败。原因是签名与设备要求不匹配或者构建时选的 API 级别低于设备固件要求。解决重新生成签名把最小 API 级别提到设备要求的档位卸载旧版本再装。别在设备上直接覆盖装不同签名的包必失败。现象四场景跑一会儿就掉帧、发烫。原因是实时阴影太多、模型面数超预算或者渲染缩放没降。解决把不动的物体标记为 Static 走烘焙光照关闭多余实时光源renderScale从 1.0 降到 0.8 测试帧率变化。发烫本质是 GPU 长期跑满降分辨率和减实时光照是最直接的两刀。注意调试时优先用真机模拟器能验证逻辑但验证不了性能和舒适度。很多晕动问题是只有戴上头显才感觉得到的。5. 装完怎么验证一份可复现的验收清单环境搭完、场景跑起来不代表这套东西能用。验收标准要落到可操作的动作上而不是「看着还行」。我一般在项目根目录放一份AcceptanceChecklist.md每次构建前过一遍把主观感受换成可打勾的条目。# 虚拟展览验收清单 ## 环境层 - [ ] 引擎版本与团队锁定记录一致 - [ ] XR 插件已启用设备列表能看到目标头显 - [ ] 构建平台模块已安装构建日志无缺失依赖警告 ## 交互层 - [ ] 头部转动画面跟手无延迟感、无拖影 - [ ] 射线 8 米内能命中展品8 米外不误触 - [ ] 点击展品能弹出详情关闭后状态复位 - [ ] 手柄双手同时操作时交互不串 ## 性能层 - [ ] 静止时帧率稳定在目标值波动不超过 5 帧 - [ ] 快速转动头部时无可感知掉帧 - [ ] 连续运行 15 分钟设备温度可接受、帧率不持续下滑 ## 内容层 - [ ] 所有展品模型无破面、无粉色材质 - [ ] 透明材质双眼观看无排序穿帮 - [ ] 背景音乐与 3D 环境音空间位置正确这份清单里最值钱的是性能层那三条。帧率波动和长时间运行的掉帧是虚拟展览上线后用户投诉最集中的点而且它们在开发机短时间测试里往往看不出来。用设备自带的性能监视器或者引擎的帧率显示叠层跑满 15 分钟看曲线比任何主观描述都可靠。还有个具体技巧验收时找没参与开发的人戴上头显走一遍什么都不教看他能不能自己找到展品、点开详情、退出菜单。开发者对交互路径太熟了会下意识绕开设计缺陷。外部测试者第一次使用时卡住的地方就是你要改的地方。从那以后我每次交付前都会强制走一遍这份清单尤其是帧率那三条不看曲线不签字。踩过的坑告诉我VR/AR 这套环境里能装起来和能用之间隔着的就是这些看起来啰嗦的验证步骤。希望这套流程能帮到你少走几个我走过的弯路。本文还有配套的精品资源点击获取