第 30 课
打包导出项目
Unity 编辑器并不会单独完成 Android 应用的全部生成工作。它先收集场景、资源、脚本和项目设置，再调用 JDK、Android SDK、NDK 与 Gradle 完成编译和组装。本课先建立这条构建链的整体认识，然后以 MuseumVR 项目为例，依次确认 Android 参数、PICO OpenXR 功能和 PICO 4 Ultra 设备连接，最后用最短流程完成真机构建。页面末尾提供按“现象—原因—位置—处理—再次确认”组织的问题处理表，帮助你从已经观察到的现象开始定位。
把 MuseumVR 构建成能在头戴设备上独立运行的应用
完成 Android 构建工具、场景列表、应用运行参数（Player Settings）与 PICO OpenXR 功能的逐项确认，把 Unity 工程生成可以安装到 PICO 4 Ultra 的 APK（安卓应用安装包）。你还会掌握直接构建、连接设备后构建并运行、ADB 命令安装，以及按照现象逐层定位问题的方法。
学完你将能够
学习目标
- 说明 Unity、JDK、Android SDK、NDK 与 Gradle 在生成 APK 时各自承担的工作。
- 使用打包准备清单确认项目、场景、构建工具、Android 参数、OpenXR 功能和设备连接。
- 确认 MainScene 已加入 Scenes In Build，并把目标平台、贴图压缩和运行设备设置正确。
- 理解包名、版本、最低系统版本、IL2CPP、ARM64、图形接口与输入系统设置对构建结果的影响。
- 为 PICO 选择 PICO OpenXR 功能、设备对应的控制器配置和手部交互支持。
- 区分 Build 与 Build And Run，并能用最简单的流程生成、安装和启动 APK。
- 使用 adb devices -l 确认设备授权，并使用 adb install 安装或覆盖安装测试包。
- 记录一次 PICO 构建使用的应用身份、OpenXR 配置、输出文件和实机结果，使成功流程可以重复。
- 按照报错现象保存有效信息、定位对应设置、只修改一个原因并再次确认结果。
- 在 PICO 4 Ultra 上依次完成冷启动、输入、漫游、交互、菜单和多媒体功能确认。
开始操作前
准备工作
- 使用安装了 Android Build Support（安卓构建支持）的 Unity 2022.3 编辑器打开 MuseumVR，并等待资源导入与脚本编译结束。
- 准备一台已开启开发者模式与 USB 调试的 PICO 4 Ultra、一根能够传输数据的 USB 线和足够的设备存储空间。
- 保存当前场景与项目设置，关闭运行状态；如果准备修改平台配置，先保留一份可恢复的项目副本。
- 打开 Console（控制台）、File → Build Settings、Edit → Project Settings 和 Edit → Preferences，便于按清单逐项确认。
- 准备能够说明项目、设备平台与版本的 APK 文件名，例如 MuseumVR-PICO-0.1.apk。
本课学习路线
按照学习模块逐步完成
每个模块都包含理解、跟随操作和独立实践。打包不是一次简单的文件保存
先理解 APK 是怎样生成的
点击构建按钮以后，Unity 会连续调用多项 Android 工具。知道每一环负责什么，错误出现时才能判断应该查看 Unity、工具链还是设备。从 Unity 项目到设备应用的完整链条
Unity 先读取 Scenes In Build（参与构建的场景列表）。列表中的第一个启用场景通常是应用启动入口；没有加入列表的场景不会自动进入安装包，因此脚本即使写得正确，设备也无法打开遗漏的场景。MuseumVR 当前启用的入口是 Assets/_Scene/MainScene.unity。
接着，Unity 会整理被场景和资源引用的模型、贴图、音频、视频、材质与脚本。选择 ASTC（自适应可伸缩纹理压缩）后，贴图会转换为移动头戴设备能够高效读取的压缩格式。第一次切换压缩格式通常要重新处理大量贴图，所以等待时间会明显变长。
C# 脚本使用 IL2CPP 构建后，会先转换成 C++，再由 Android NDK（原生开发工具包）编译为 ARM64 处理器可以执行的本机代码。JDK 提供 Java 构建环境，Android SDK 提供平台工具和系统接口，Gradle 则负责把代码、资源、清单和依赖组装成 APK。
最后，Build 只生成 APK；Build And Run 会在生成 APK 后继续调用设备工具安装并启动应用。因此“生成成功”“安装成功”和“设备运行正确”是三个不同的完成条件，必须分别确认。
构建链中每一环的职责
看到错误名称时，先判断它属于哪一环，再打开对应位置。
左右滑动表格，可查看完整内容
| 环节 | 负责什么 | 常见失败表现 | 首先查看 |
|---|---|---|---|
| Unity 项目 | 收集场景、资源、脚本和构建参数 | 场景遗漏、脚本编译失败、资源引用丢失 | Console 与 Scenes In Build |
| JDK | 提供 Java 编译与签名所需环境 | 找不到 Java、版本或路径错误 | Preferences → External Tools |
| Android SDK | 提供 Android 平台、ADB 与系统接口 | 缺少平台、许可证问题、找不到设备 | External Tools 与 adb devices |
| Android NDK | 把 IL2CPP 产生的 C++ 编译为 ARM64 代码 | 本机代码编译失败或架构不匹配 | External Tools、IL2CPP 与 ARM64 |
| Gradle | 合并清单、依赖、代码和资源并生成 APK | 依赖冲突、清单合并失败、组装失败 | Console 中第一条有效 Gradle 错误 |
| ADB | 识别设备、安装 APK 并返回安装结果 | 设备离线、未授权、安装被拒绝 | USB 调试授权与 adb devices |
把一次构建拆成三个完成条件
在纸上或学习记录中写出“生成、安装、运行”三行，并为每一行写一个能观察到的完成证据。
- 生成：指定位置出现本次构建的 APK，文件大小不为 0。
- 安装：Unity 或 ADB 明确返回安装成功，设备中出现对应应用。
- 运行：应用能够进入 MainScene，头部跟踪和主要交互可以正常操作。
第一次逐项确认，以后重点确认发生变化的部分
用打包准备清单消除遗漏
打包失败经常不是复杂技术问题，而是场景、平台、设备或平台功能漏选。点击构建之前按顺序完成这张清单，可以把错误限制在较小范围内。打包前必做准备清单
每一行都要得到可以观察的证据；不要只凭记忆认为以前设置过。
左右滑动表格，可查看完整内容
| 完成 | 准备项目 | 打开位置 | 完成标准 |
|---|---|---|---|
| □ | 保存项目 | File → Save 与 Save Project | 场景和资源改动已经保存 |
| □ | 脚本可以编译 | Console | 没有红色脚本编译错误 |
| □ | 入口场景已加入 | Build Settings → Scenes In Build | MainScene 已启用并位于列表中 |
| □ | 目标平台正确 | Build Settings → Platform | 已切换为 Android |
| □ | 贴图压缩正确 | Build Settings → Texture Compression | 选择 ASTC，并等待贴图处理完成 |
| □ | 构建工具齐全 | Preferences → External Tools | JDK、SDK、NDK、Gradle 均有有效位置 |
| □ | 应用身份明确 | Player → Company Name、Product Name、Version 与包名 | 测试包可辨认；发布包不再使用默认组织名 |
| □ | Android 代码与架构正确 | Player → Other Settings | 最低 API 29、IL2CPP、ARM64 |
| □ | 图形接口明确 | Player → Other Settings → Graphics APIs | 自动选择已关闭，当前项目保留 Vulkan 与 OpenGLES3 |
| □ | 输入系统符合项目 | Player → Active Input Handling | 当前项目记录为 Both；切换前确认没有旧输入依赖 |
| □ | Android OpenXR 已启用 | XR Plug-in Management 的 Android 标签 | OpenXR 加载器已启用 |
| □ | 平台功能匹配 | OpenXR → Features | 只启用本次设备需要的平台支持与交互配置 |
| □ | 项目验证通过 | XR Plug-in Management → Project Validation | 没有阻止当前平台运行的错误 |
| □ | 模拟测试已退出 | XR Interaction Toolkit 与电脑端 XR 设置 | 不让设备模拟器或串流预览接管真机输入 |
| □ | 设备已授权 | Build Settings → Run Device 与 adb devices | 设备可见且状态为 device，不是 unauthorized 或 offline |
| □ | 设备条件正常 | 头戴设备 | 电量、存储空间和开发者模式满足测试 |
| □ | 输出位置与文件名明确 | 构建保存窗口 | 使用独立 Builds 文件夹，并在文件名中区分平台与版本 |
| □ | 发布信息已准备 | 平台后台与 Player 发布设置 | 仅本地测试可暂不填商店 App ID；发布时补齐身份、签名与平台资料 |
下载第 30 课打包准备与实机确认清单
下载 Markdown 清单后，可以为每次 PICO 构建复制一份，勾选设置、记录 APK 名称和真机确认结果。
- 包含打包前准备、最短构建流程和 PICO 实机功能确认三部分
- 适合保存在每次构建输出文件夹中，便于复现成功设置
完成一次真实的清单核对
先不要点击 Build。按照表格打开每个位置，把无法直接确认的项目标记出来。
- 确认本次目标设备是 PICO 4 Ultra。
- 至少记录一个已经通过的证据，例如 MainScene 在场景列表中的位置。
- 至少记录一个需要处理的项目，例如默认组织名、输入系统 Both 或设备尚未授权。
- 所有阻止构建的项目处理完后，再进入下一模块。
先让电脑具备构建能力，再告诉 Unity 要打包什么
确认 Android 工具与 Build Settings
External Tools 决定 Unity 能否调用 Android 工具，Build Settings 决定哪些场景进入 APK、面向哪个平台构建以及构建后发送到哪台设备。确认四项 Android 外部工具
- 01
打开 Edit → Preferences → External Tools。
- 02
找到 Android 区域，确认 JDK、Android SDK、Android NDK 和 Gradle 都有有效路径。
- 03
优先使用随当前 Unity 编辑器安装的工具版本。若某一项为空，先在 Unity Hub 为这个编辑器补装 Android Build Support、Android SDK & NDK Tools 和 OpenJDK。
- 04
补装完成后重新打开项目，再次确认四项路径；不要从不同 Unity 版本随意拼接 JDK、SDK、NDK 和 Gradle。
配置 Build Settings
- 01
打开 Assets/_Scene/MainScene.unity，然后选择 File → Build Settings。
- 02
在 Scenes In Build 中确认 Assets/_Scene/MainScene.unity 已勾选。若列表为空，点击 Add Open Scenes；有多个场景时按实际启动与跳转关系全部加入。
- 03
在 Platform 列表中选择 Android。若右侧显示 Switch Platform，点击并等待资源重新导入；只有平台切换完成后再继续。
- 04
把 Texture Compression 设为 ASTC。第一次转换会处理项目贴图，等待进度结束，不要强制关闭编辑器。
- 05
连接设备后点击 Run Device 旁的 Refresh，并选择本次目标设备。设备不出现时先处理 USB 与 ADB，不要反复点击构建。
按从上到下的顺序观察：先确认 MainScene 在 Scenes In Build，再确认 Android、ASTC 和 Run Device。截图用于定位设置区域，具体设备名称以你实际连接的头戴设备为准。
点击图片可以查看完整截图为什么使用 ASTC
ASTC 按像素区块压缩贴图，PICO 4 Ultra 的移动芯片能够直接处理这种格式。它能在画质、安装包大小和显存占用之间取得较好的平衡。本项目可从默认 6×6 区块开始；区块越小通常画质越高、占用越大，区块越大通常压缩越强、细节损失越多。
切换 ASTC 后，可以选择一张贴图，在属性面板底部预览导入结果。不要因为第一次转换较慢就频繁切换压缩格式；项目中不再使用的大型图片也应从构建引用中移除。
用证据确认构建内容
完成设置后，不关闭窗口，逐项读出 MainScene 路径、目标平台、贴图压缩模式和 Run Device。
- 确认场景左侧复选框已勾选。
- 确认 Android 已成为当前平台，而不是只被鼠标选中。
- 确认 ASTC 转换已经结束。
- 确认 Run Device 对应本次要测试的设备。
应用身份、系统兼容性和处理器架构都在这里决定
读懂并确认 Player Settings
Player Settings（播放器设置）不是画面播放器，而是最终应用的身份与运行规则。这里的值会影响安装覆盖、设备兼容、脚本编译和输入。MuseumVR 当前可核对的 Android 设置
这些值来自项目本身。带有“发布前修改”的项目可以用于本地测试，但不应直接当作正式发布信息。
左右滑动表格，可查看完整内容
| 设置 | 当前值 | 含义 | 本次处理 |
|---|---|---|---|
| Company Name | DefaultCompany | 组织名，也是默认包名的一部分 | 本地测试可用；发布前改为稳定组织名 |
| Product Name | MuseumVR | 设备资源库中用于识别应用的名称 | 确认名称清楚且不与测试包混淆 |
| Version | 0.1 | 面向使用者显示的版本 | 每次交付按规则更新 |
| Package Name | com.DefaultCompany.MuseumVR | Android 用于区分应用的唯一标识 | 发布后保持稳定；更改后会被视为另一应用 |
| Minimum API Level | Android 10 / API 29 | 允许安装的最低 Android 系统接口级别 | 保持 29 |
| Target API Level | Automatic | 构建时面向的 Android 接口级别 | 使用当前工具链可用的自动目标 |
| Scripting Backend | IL2CPP | 把 C# 转换为 C++ 后编译为本机代码 | 保持 IL2CPP |
| Target Architectures | ARM64 | 生成 64 位 ARM 处理器代码 | 保持 ARM64 |
| Graphics APIs | Vulkan、OpenGLES3 | 应用可使用的移动图形接口 | 自动选择已关闭；保留项目现有顺序 |
| Active Input Handling | Both | 新输入系统与旧输入系统同时启用 | 项目当前可运行状态；只有确认无旧输入依赖后才改为新输入系统 |
包名、版本名和版本代码不要混为一谈
Package Name（包名）是 Android 识别应用的主键。相同包名的新版通常会尝试覆盖旧版；包名不同会并列安装。正式发布后随意修改包名，会让设备和商店把它当作另一个应用。
Version 是学生在界面中容易看到的版本名称；Bundle Version Code 是 Android 比较新旧的整数。覆盖安装时，新包的版本代码不能低于设备中已经安装的版本代码。
签名也参与覆盖判断。两个 APK 即使包名相同，只要签名密钥不同，Android 也不会允许直接覆盖。测试阶段如果遇到签名冲突，可以先确认旧应用是否有需要保留的数据，再决定卸载旧版或恢复原签名。
按顺序确认 Android 标签页
- 01
在 Build Settings 点击 Player Settings，并确认顶部平台图标选择 Android。
- 02
确认 Company Name、Product Name、Version、Package Name 和 Bundle Version Code。
- 03
展开 Other Settings，确认 Minimum API Level 为 Android 10 / API 29，Target API Level 使用项目当前的 Automatic。
- 04
确认 Scripting Backend 为 IL2CPP，Target Architectures 只勾选 ARM64。
- 05
确认 Auto Graphics API 已关闭，当前列表包含 Vulkan 与 OpenGLES3。不要为了排错同时随意增删多个图形接口。
- 06
查看 Active Input Handling。MuseumVR 当前保存为 Both；若决定切到 Input System Package (New)，先确认项目和插件没有使用旧输入接口，并接受 Unity 重启。
解释三个不能随意修改的值
用自己的话分别说明 Package Name、Bundle Version Code 和签名为什么会影响覆盖安装。
- 包名决定系统认为是不是同一个应用。
- 版本代码决定新包是否允许降级覆盖。
- 签名决定两个同包名安装包是否来自同一发布者。
Android 设置解决能否运行，OpenXR 设置解决怎样识别设备能力
为 PICO 配置 OpenXR 功能
OpenXR 可以让 Unity 使用一套通用接口读取头戴设备、控制器和手部数据；PICO 平台功能再补充设备需要的能力。控制器型号、手部跟踪和厂商支持必须与本次目标设备一致。当前 MuseumVR 的 PICO 能力组合
Android 的 XR Plug-in Management 当前使用 OpenXR 加载器。OpenXR 可以理解为 Unity 与不同头戴设备之间的一套通用接口；PICO Support 和 PICO OpenXR Features 再为它补充 PICO 平台能力。
项目当前启用了 PICO4 Ultra Touch Controller Profile、Hand Interaction Profile、Hand Tracking Subsystem、PICO OpenXR Features 与 PICO Support。这与 MuseumVR 同时使用 PICO 4 Ultra 控制器和手部交互的功能相对应。
在 PICO 支持设置中选择 Controllers And Hands（同时使用控制器与手部），应用才能在两种输入方式之间按设备状态切换。只选择 Controllers 会缺少手部输入，只选择 Hands 则不符合本项目同时使用手柄的需求。
Project Validation（项目验证）会提示缺少或冲突的设置。Fix（自动修复）只是按提示修改一次设置，完成后仍要回到 Features，确认 PICO 4 Ultra 控制器、手部交互和手部跟踪仍然启用，并移除与当前设备无关的控制器配置。
设备型号不同，控制器配置也要替换。例如 PICO 4、PICO Neo3 与 PICO 4 Ultra 使用不同的控制器配置。配置文件的作用是告诉 OpenXR 按键、摇杆和姿态来自哪类设备，不是“勾得越多越保险”。
从 Android OpenXR 到项目验证
- 01
打开 Edit → Project Settings → XR Plug-in Management，切换到 Android 标签，确认 OpenXR 已启用。
- 02
进入 OpenXR 的 Features 列表，启用 PICO Support 与 PICO OpenXR Features。
- 03
选择与真实设备对应的 PICO 控制器配置。MuseumVR 当前目标是 PICO 4 Ultra，因此使用 PICO4 Ultra Touch Controller Profile。
- 04
保留 Hand Interaction Profile 和 Hand Tracking Subsystem，让 OpenXR 能接收标准手部关节与手势数据。
- 05
打开 PICO 支持设置，把交互模式设为 Controllers And Hands，并确认项目需要的手部跟踪能力已开启。只启用项目实际使用的功能，不要为尚未实现的眼动、空间网格等能力增加依赖。
- 06
进入 Project Validation（项目验证），处理阻止当前配置工作的错误。若使用 Fix，完成后必须返回 Features，重新确认 PICO4 Ultra Touch Controller Profile、Hand Interaction Profile 与 Hand Tracking Subsystem 仍然启用，并确认 PICO Neo3、PICO 4 或其他设备的控制器配置没有被意外替换进来。
App ID、本地测试和正式发布
PICO 平台设置中的 App ID 用于把项目和开发者平台上的应用记录关联起来。本地连接设备测试普通功能时，可以先完成 APK 构建与安装；准备上传平台时，必须创建对应应用并填写正确 App ID，同时完成包名、版本、签名和平台资料。
App ID 不是包名。App ID 来自平台后台，Package Name 来自 Player Settings。两者都属于应用身份的一部分，但用途不同，不能互相代替。
让真机成为唯一输入来源
- 01
退出 Unity 运行状态，关闭 XR Device Simulator（XR 设备模拟器）的自动启用。
- 02
如果之前使用 PICO Live Preview 串流预览，在电脑平台的 XR 设置中关闭对应预览功能。
- 03
再次确认 Android 平台的 OpenXR 与 PICO 功能仍然启用。电脑标签和 Android 标签是两套设置，不要关闭错误的平台。
- 04
连接 PICO，确认设备已经接受这台电脑的 USB 调试授权。
用项目功能反推 OpenXR 选项
列出 MuseumVR 在 PICO 4 Ultra 上需要的输入能力，并在 Features 中逐项找到对应设置。
- 控制器姿态与按键：PICO4 Ultra Touch Controller Profile。
- 标准手势交互：Hand Interaction Profile。
- 手部骨骼数据：Hand Tracking Subsystem。
- 厂商平台能力：PICO Support 与 PICO OpenXR Features。
- 交互模式：Controllers And Hands。
设置确认后，日常构建只保留一条主线
按最简单流程构建并运行
第一次打包需要逐项确认；设置稳定以后，每次真机测试可以沿着一条最短流程完成。流程中的任何一步没有通过，都先停在当前步骤处理。
最短主线只有六步：保存场景与项目 → 切换 Android → 确认 Player 设置与构建设置 → 启用 OpenXR 与 PICO 功能 → 构建 APK → 安装到 PICO 并确认主要功能。任何一步失败，都不要跳过它继续尝试后续步骤。
手机上可左右滑动；点击图片可以查看完整图第一次设置完成后的六步构建法
- 01
保存 MainScene，确认 Console 没有红色脚本编译错误。
- 02
打开 Build Settings，切换到 Android；确认 MainScene 已启用，并选择 ASTC 纹理压缩。
- 03
确认 Player Settings 中的应用身份、API 级别、图形接口、IL2CPP、ARM64 与输入处理设置。
- 04
在 Android 的 XR Plug-in Management 中启用 OpenXR，并只保留 PICO 4 Ultra 需要的平台、控制器与手部功能。
- 05
选择 Build 或 Build And Run 生成 APK；若使用 Build And Run，先连接设备、接受 USB 调试授权并确认 Run Device。
- 06
把 APK 安装到目标头戴设备并启动，随后执行完整真机确认清单，不能只以“看到启动画面”为完成标准。
Build 与 Build And Run 的选择
两个按钮都会生成 APK，区别在于是否继续安装和启动。
左右滑动表格，可查看完整内容
| 按钮 | 得到 APK | 自动安装 | 自动启动 | 适合场景 |
|---|---|---|---|---|
| Build | 是 | 否 | 否 | 只生成安装包、保存版本或交给另一台设备安装 |
| Build And Run | 是 | 是 | 是 | 设备已连接，希望立刻完成真机测试 |
执行一次可辨认的构建
使用 Build And Run 生成测试包，并让文件名能够回答“哪个平台、哪个版本”。
- PICO 示例：MuseumVR-PICO-0.1.apk。
- 构建结束后确认 APK 的修改时间是本次操作时间，文件大小不为 0。
- 保留对应准备清单，记录设备型号和实机结果。
已经有 APK 时，不必重新构建项目
单独安装 APK 并确认设备连接
使用 Build 得到 APK 后，可以把文件复制到设备中手动安装，也可以使用 ADB（安卓调试桥）从电脑安装。ADB 的文字结果更适合定位设备授权和覆盖安装问题。方法一：复制到设备后手动安装
用数据线连接设备，在 Windows 文件资源管理器中打开设备存储，把 APK 复制到 Download 等容易找到的位置。然后在设备的文件管理器中选择 APK 并确认安装。
安装完成后，PICO 测试应用通常可从资源库的未知来源分类打开。请根据 Product Name 和包名确认启动的是本次生成的 MuseumVR。
这种方法操作直观，但遇到失败时提示可能较少。如果应用没有出现、覆盖失败或设备没有被电脑识别，使用 ADB 能得到更明确的状态。
adb devices -l
adb install -r "MuseumVR-PICO-0.1.apk"在 APK 所在文件夹打开终端。文件名或路径含空格时必须使用英文双引号包住完整路径。-r 表示在签名和版本规则允许时覆盖安装并保留应用数据。
adb devices 返回状态
先让设备状态正常，再执行安装命令。
左右滑动表格，可查看完整内容
| 状态 | 含义 | 下一步 |
|---|---|---|
| device | 设备已连接并授权 | 可以执行 adb install |
| unauthorized | 电脑尚未获得 USB 调试授权 | 戴上设备接受授权，再重新执行命令 |
| offline | 连接存在但 ADB 会话不可用 | 重新插线、重启 ADB 或设备后再次确认 |
| 列表为空 | 电脑没有识别到可用 ADB 设备 | 确认开发者模式、USB 模式、数据线、接口和驱动 |
| 多台设备 | ADB 不知道默认目标 | 断开无关设备，或使用 -s 序列号指定目标 |
完成一次独立安装
不重新点击 Unity 构建，使用现有 APK 完成设备识别、安装和手动启动。
- 执行 adb devices -l，确认目标序列号后的状态为 device。
- 执行 adb install -r，并等待明确的 Success。
- 在设备资源库中找到 MuseumVR 并手动打开。
- 如果失败，保留完整错误行并在故障表中按现象查找。
先判断问题发生在哪一步，再处理一个明确原因
按阶段定位构建与安装问题
构建失败时，最后一行通常只是结果摘要。先保存第一条有具体内容的错误，再判断问题属于项目编译、APK 生成、设备安装、应用启动还是交互运行。这样可以少走弯路，也能知道本次处理为什么有效。先把问题放回它发生的阶段
如果 Console 已有红色脚本错误，问题还停留在项目编译阶段；如果错误包含 Gradle、Manifest 或 IL2CPP，说明 Unity 已经进入安卓组装阶段；如果 APK 已经生成却无法进入设备，就转到 ADB、包名、版本代码和签名。
应用能够安装但打开后黑屏、闪退或没有进入 MainScene，说明问题已经来到启动阶段；应用能进入博物馆但头部、控制器或手部没有响应，则应查看 Android OpenXR 与 PICO 输入配置。
一次只根据一条明确线索修改一个位置。修改后回到原来的步骤再次操作，观察同一问题是否消失，同时避免破坏已经正常的功能。
打包与安装问题定位表
先找到最接近的现象，再从对应位置读取完整信息。
左右滑动表格，可查看完整内容
| 现象 | 问题阶段 | 可能原因 | 打开位置 | 处理方法 |
|---|---|---|---|---|
| Build 按钮不可用或 Android 不在列表 | 构建工具 | 当前编辑器未安装安卓构建模块 | Unity Hub → 当前编辑器 → Add modules | 补齐配套的 Android Build Support、SDK、NDK 与 OpenJDK |
| 构建前已有红色脚本错误 | 项目编译 | C# 代码或程序集引用不能编译 | Console 第一条红色错误 | 先修复代码与引用，等待 Unity 重新编译 |
| MainScene 没有进入应用 | 构建内容 | 入口场景未加入构建 | Scenes In Build | 加入并启用 Assets/_Scene/MainScene.unity |
| Gradle 提示 Manifest merger failed 或 Duplicate class | 安卓组装 | 插件清单、原生库或依赖重复 | Console 第一条清单或重复类详情 | 根据具体重复项保留唯一依赖，不要整包盲删 |
| IL2CPP 或架构编译失败 | 本机代码 | 脚本后端、处理器架构或 NDK 不匹配 | Other Settings 与 External Tools | 恢复 IL2CPP、ARM64，并使用当前 Unity 配套 NDK |
| Project Validation 出现红色提示 | PICO OpenXR | 缺少必需选项或存在冲突配置 | Project Validation 与 Features | 处理提示后重新确认 PICO 4 Ultra 控制器和手部配置 |
| Run Device 没有设备 | 设备连接 | 开发者模式、数据线、驱动或授权未就绪 | PICO 授权提示与 adb devices -l | 确认开发者模式、数据线、USB 调试和设备授权 |
| ADB 显示 unauthorized | 设备授权 | PICO 尚未信任这台电脑 | 头戴设备内的 USB 调试提示 | 在 PICO 中允许这台电脑调试 |
| ADB 显示 offline | ADB 会话 | 连接存在但会话暂时不可用 | 数据线、接口和设备状态 | 重新连接，必要时重启 ADB 与设备 |
| INSTALL_FAILED_UPDATE_INCOMPATIBLE | 设备安装 | 同包名的新旧应用签名不同 | 包名、签名与旧应用 | 恢复同一签名，或确认数据无需保留后卸载旧包 |
| VERSION_DOWNGRADE | 设备安装 | 新 APK 的版本代码低于已安装版本 | Bundle Version Code | 提高版本代码，或确认数据无需保留后卸载旧版 |
| 安装后黑屏、闪退或没有进入博物馆 | 应用启动 | 入口场景遗漏或出现运行时异常 | MainScene 与设备日志 | 根据第一条运行错误处理场景或引用 |
| 有画面但控制器或手部无输入 | 交互运行 | 设备配置或手部功能没有对应启用 | Android OpenXR Features | 确认 PICO 4 Ultra 控制器、Hand Interaction 与 Hand Tracking |
| 画面冻结或输入被电脑模拟器接管 | 交互运行 | 模拟器或串流预览仍在提供输入 | XR Device Simulator 与电脑预览 | 关闭模拟或串流预览后独立启动 PICO 应用 |
按五步处理一次真实问题
- 01
写下刚才执行的操作、目标设备和完整现象，不只记录一句“失败了”。
- 02
保留第一条有具体原因的错误，以及它前后的相关内容。
- 03
判断问题属于项目编译、APK 生成、设备安装、应用启动还是交互运行。
- 04
只修改一个与当前线索直接相关的设置，并记住修改前的值。
- 05
重新执行原来的操作，确认同一问题是否消失；若出现新现象，再从新阶段继续定位。
根据现象选择起点
阅读下面三个情境，不修改项目设置，先说出问题属于哪个阶段以及第一处应该打开的位置。
- 情境一：Console 已经出现 C# 编译错误，Build 按钮不可用。
- 情境二：APK 已生成，adb install 返回 VERSION_DOWNGRADE。
- 情境三：应用能进入 MainScene，但左右控制器完全没有响应。
- 为每个情境写出“阶段—位置—只处理的一项内容—再次观察的结果”。
APK 能打开只是起点，作品功能全部可用才是本课成果
完成 PICO 实机功能与成果确认
最后一步必须离开 Unity 编辑器，在 PICO 4 Ultra 上从资源库冷启动应用，再依次操作头部、控制器、手部、漫游、作品交互、菜单、音视频和作品说明牌。完成后把构建身份、APK 与实机结果放进同一份记录，下一次才能稳定重复。从 APK 到作品完成的五层结果
第一层是生成：输出文件夹中出现本次 APK，文件大小不为 0。第二层是安装：Unity 或 ADB 明确返回成功，PICO 资源库中出现 MuseumVR。第三层是启动：完全退出后重新打开，应用稳定进入 MainScene。
第四层是输入：头部姿态、左右控制器与手部跟踪都能驱动对应对象。第五层是课程功能：场景漫游、作品交互、菜单与设置、音视频和作品说明牌都按前面课程完成的方式运行。
任何一层失败都不等于整次构建无效，它只说明应该返回对应阶段继续处理。记录时写清楚通过到哪一层、在哪一项停止，下一次就能直接从有效线索开始。
PICO 构建记录应该包含什么
把这些内容与 APK 放在一起，下一次就能辨认安装包并恢复同一套构建条件。
左右滑动表格，可查看完整内容
| 记录内容 | 从哪里读取 | 示例 | 作用 |
|---|---|---|---|
| 目标设备 | PICO 系统信息与 Run Device | PICO 4 Ultra | 说明本次面向哪台设备 |
| Unity 版本 | Unity 标题栏或 Hub | 2022.3 LTS | 避免编辑器和工具链不一致 |
| 包名 | Player Settings | com.DefaultCompany.MuseumVR | 确认 Android 应用身份 |
| Version 与 Version Code | Player Settings | 0.1 / 1 | 判断显示版本和覆盖安装顺序 |
| 代码与处理器 | Other Settings | IL2CPP / ARM64 | 确认设备可执行代码的生成方式 |
| PICO 输入配置 | OpenXR Features | PICO 4 Ultra 控制器、手部交互与跟踪 | 说明控制器和双手为何可用 |
| 签名类型 | Publishing Settings | 调试签名 | 判断能否覆盖设备中的旧应用 |
| APK 文件 | 构建输出目录 | MuseumVR-PICO-0.1.apk | 保存文件路径、大小和生成时间 |
| 安装结果 | Unity 或 ADB | Success | 证明 APK 已进入设备 |
| 实机结果 | PICO 4 Ultra | 冷启动、头部与手部输入、课程功能均正常 | 证明作品功能真正可用 |
PICO 实机功能确认清单
APK 能打开只是起点。每一项都要在脱离编辑器的头戴设备上实际操作。
左右滑动表格，可查看完整内容
| 完成 | 功能项目 | 操作方法 | 完成标准 |
|---|---|---|---|
| □ | APK 文件 | 查看文件名、大小、修改时间和版本记录 | 平台与版本正确，文件不为 0 |
| □ | 安装结果 | 查看 Unity 或 adb install 输出 | 明确显示安装成功 |
| □ | 冷启动 | 完全退出应用后从资源库重新打开 | 稳定进入 MainScene，不黑屏、不冻结、不闪退 |
| □ | 头部跟踪 | 左右转头并上下观察 | 画面及时跟随头部姿态，没有被模拟器锁定 |
| □ | 控制器 | 移动双手柄，测试按键、摇杆与射线 | 左右手姿态和输入正确 |
| □ | 手部跟踪 | 放下控制器，使用双手完成交互 | 手模型与手势能够被识别 |
| □ | 场景漫游 | 连续移动、瞬移、转向并靠近墙体 | 移动正常，碰撞不会穿墙，门洞可通过 |
| □ | 作品交互 | 抓取、放回至少一件可交互作品 | 高亮、抓取和插槽恢复正常 |
| □ | 系统菜单 | 打开、拖拽并切换各页面 | 菜单位置、导航和按钮交互正常 |
| □ | 设置功能 | 切换音乐、解说、风格、画面并执行重置 | 状态变化符合页面说明，重置回到默认状态 |
| □ | 多媒体 | 播放视频、背景音乐和一段作品解说 | 画面与声音正常，暂停和停止可用 |
| □ | 作品说明牌 | 靠近并面向作品，再转身离开 | 正确图片随条件显示和隐藏，解说状态同步 |
| □ | 再次启动 | 结束应用后第二次启动 | 不会因首次缓存或权限状态而失败 |
| □ | 设备记录 | 记录平台、型号、系统、APK 名称和版本 | 他人能够根据记录复现本次测试 |
完成一次 PICO 实机功能确认
安装刚生成的 APK，从完全退出状态重新打开应用，再按清单实际操作每项功能。发现问题时记录真实现象并返回上一模块定位，不需要人为制造故障。
- 完全结束 MuseumVR，再从 PICO 资源库冷启动，确认稳定进入 MainScene。
- 依次操作头部、左右控制器、手部、移动、瞬移、转向和场景碰撞。
- 继续操作作品抓取与放回、系统菜单、设置与重置、视频、音乐、作品解说和说明牌。
- 记录每项结果；如果某项失败，写下现象和第一条有效信息，定位后重新操作该项。
- 全部完成后退出应用并再次启动，确认第二次启动仍然正常。
把知识变成作品
本课练习
请按顺序完成以下任务，并保存自己的学习成果。- 01
复制下载清单，为本次 PICO 构建立一份记录，填写应用身份、构建设置、APK 信息和实机结果。
- 02
不看页面，用自己的话画出 Unity、IL2CPP、NDK、Gradle、APK 和 ADB 的先后关系。
- 03
使用 Build 只生成一次 APK，再用 adb devices -l 与 adb install -r 完成独立安装。
- 04
分别解释 Package Name、Version、Bundle Version Code 和签名对应用识别与覆盖安装的影响。
- 05
在 OpenXR Features 中指出 PICO 4 Ultra 所需的控制器、手部交互、手部跟踪和平台支持。
- 06
根据教师给出的 unauthorized、VERSION_DOWNGRADE 或无输入情境，写出问题阶段、首先打开的位置和再次观察的结果。
- 07
完成一次脱离 Unity 编辑器的冷启动和全部功能操作，任何失败项都使用问题定位表继续处理。
- 08
为 APK 使用包含项目、平台和版本的文件名，并把准备清单与 PICO 构建记录放在同一输出目录。
需要进一步确认时
本课参考资料
打开官方文档，核对软件设置、组件参数和设备说明。把本课进度保存下来
登录后可以保存浏览内容、有效学习时间、完成状态和答题参与记录。