expo-horizon

Expo Horizon：将 Expo SDK 迁移到 Meta Quest

Software Mansion 为使用 expo-horizon 软件包为 Expo 应用添加 Meta Quest 支持提供的生产指南。

此技能不包含文档副本。 对于以下任何任务，都应始终使用 webfetch 获取链接中的官方 README 或 Meta 文档页面，以了解最新的安装步骤、插件选项、API 范围和功能矩阵。此技能仅记录决策树、关键规则，以及 Agent 经常忽略的非显而易见的注意事项。

决策树

What do you need to do?
│
├── Starting from scratch or adding Quest support to an existing Expo app?
│   └── Follow the "Setup Workflow" below (do NOT auto-install location or
│       notifications packages) and webfetch: expo-horizon-core README
│       ├── Install expo-horizon-core
│       ├── Configure the config plugin (horizonAppId, panel size, supportedDevices)
│       ├── Add quest/mobile build scripts
│       ├── Add runtime device detection (isHorizonDevice, isHorizonBuild)
│       └── Detect expo-location / expo-notifications, then ASK before migrating
│
├── Need location services on Quest?
│   └── Webfetch: expo-horizon-location README
│       ├── Replace expo-location with expo-horizon-location
│       ├── Review the feature support matrix
│       └── Guard unsupported calls (heading, geocoding, geofencing, background)
│
├── Need push notifications on Quest?
│   └── Webfetch: expo-horizon-notifications README
│       ├── Replace expo-notifications with expo-horizon-notifications
│       ├── Configure horizonAppId in expo-horizon-core
│       ├── Use getDevicePushTokenAsync (Expo Push Service is not supported)
│       └── Skip badge counts (not supported on Quest)
│
└── Need to build, run, or publish for Quest?
    └── Webfetch: expo-horizon-core README (build variants) + Meta docs below
        ├── Build variants: questDebug, questRelease, mobileDebug, mobileRelease
        ├── Meta Quest Developer Hub (device management, sideloading)
        └── Meta Horizon Store manifest requirements

设置工作流（为现有 Expo 应用添加 Quest 支持）

用户要求添加 Meta Quest 支持时，请按顺序执行以下步骤。不要将步骤 2 和步骤 3 合并为一条安装命令——安装同级软件包需要获得用户的明确确认。

1. 安装并配置 expo-horizon-core。

   • 运行 npx expo install expo-horizon-core。
   • 写入配置前，先询问用户配置插件的值。 在一条提示中列出所有选项，让用户一次性粘贴自定义值或接受默认值。每个选项单独占一行，并在方括号中显示默认值，例如：

     我会将 expo-horizon-core 配置插件添加到 app.json。请确认或修改每个值（按 Enter / 回复 "default" 可接受方括号中的默认值）：

     • supportedDevices [quest2|quest3|quest3s] — 应用支持的 Quest 设备，以竖线分隔（提交到 Meta Horizon Store 必须设置）。
     • horizonAppId [空] — Meta Horizon 应用 ID。除非计划使用推送通知，否则留空；expo-horizon-notifications 需要此 ID 才能发放设备推送令牌。
     • defaultWidth [1024dp] — 默认面板宽度。留空则不设置。
     • defaultHeight [640dp] — 默认面板高度。留空则不设置。如果设置了宽度/高度，请确保 Expo 的 orientation 与之匹配（宽屏面板使用 "landscape"）。
     • disableVrHeadtracking [false] — 设为 true 可省略清单中的 android.hardware.vr.headtracking 条目。
     • allowBackup [false] — Meta 建议敏感数据使用 false；只有在 Quest 构建中需要 Android 备份时才设为 true。

   • 仅在用户回复后写入插件配置。用户留空的选项应省略，以便应用软件包自身的默认值（不要为 horizonAppId、defaultWidth 或 defaultHeight 写入空字符串）。
   • 将 quest / mobile 构建脚本添加到 package.json。
   • 运行 npx expo prebuild --clean。
   • 提问前，使用 webfetch 获取 expo-horizon-core README，以确认当前的选项名称和默认值——这些默认值可能会随版本更新而改变。

2. 检测现有的位置 / 通知软件包。暂时不要安装对应的 horizon 软件包。

   • 阅读项目的 package.json。
   • 检查 dependencies 和 devDependencies 中是否包含 expo-location 和 expo-notifications。
   • 如果两者都不存在，则跳过此工作流的其余步骤——用户无需迁移。

3. 对于每个检测到的包，在迁移前询问用户。

   • 如果发现 expo-location，请询问：

     "我在你的项目中发现了 expo-location。你想让我将它替换为 expo-horizon-location，以便在 Meta Quest 上使用位置功能吗？（Quest 没有 GPS、航向、地理编码或地理围栏功能；对于不受支持的调用，需要通过 ExpoHorizon.isHorizonDevice 加以保护。）"

   • 如果发现 expo-notifications，请询问：

     "我在你的项目中发现了 expo-notifications。你想让我将它替换为 expo-horizon-notifications，以便在 Meta Quest 上使用推送通知吗？这需要在核心配置插件中设置 horizonAppId，使用 Meta 的推送服务（而非 Expo Push Service），且不支持徽标计数或 getExpoPushTokenAsync。"

   • 如果两个包都存在，请一并提出问题。
   • 在用户明确答复前，不要为这些包运行任何安装或编辑操作。

4. 只有在用户确认后，才为获批的包执行迁移：

   • 安装 Horizon 对应包（npx expo install expo-horizon-location 或 expo-horizon-notifications）。
   • 卸载原包（npm uninstall expo-location 或 expo-notifications）。
   • 将所有 import 语句更新为 Horizon 包名。
   • 对于通知：确保在 expo-horizon-core 插件配置中设置了 horizonAppId，并将 expo-horizon-notifications 添加到 plugins 数组。
   • 再次运行 npx expo prebuild --clean。
   • Webfetch 相关 README（位置或通知），查看完整的功能支持矩阵，并使用 ExpoHorizon.isHorizonDevice 保护不受支持的调用。

5. 如果用户拒绝迁移，保留原包不变，并在摘要中注明：在完成迁移前，功能 X（位置／通知）无法在 quest 构建中使用。

关键规则

• 始终先安装 expo-horizon-core。 所有其他 expo-horizon 包都依赖它；它会设置其他包所需的 quest／mobile 构建变体。

• 绝不自动安装 expo-horizon-location 或 expo-horizon-notifications。 添加 Quest 支持时，检测 package.json 中是否存在 expo-location／expo-notifications 依赖，并询问用户是否迁移各包。仅安装和配置用户明确批准的包。请参阅上方的设置工作流。

• 仅在 Meta Quest 设备上使用 quest 构建变体。 在标准 Android 手机上运行 questDebug 或 questRelease 构建不受支持，且行为可能异常。

• 在配置插件中设置 supportedDevices。 这是提交到 Meta Horizon Store 的必要配置。使用竖线分隔的值："quest2|quest3|quest3s"。

• 更改任何插件配置后，运行 npx expo prebuild --clean。 配置插件会在 prebuild 时修改原生项目文件。过时的原生项目不会反映你的更改。

• 替换导入语句，而不只是替换包。 从 expo-location 或 expo-notifications 迁移时，将所有导入语句更新为使用新的包名（expo-horizon-location、expo-horizon-notifications）。

• Quest 没有 GPS、磁传感器或地理编码器。 航向、地理编码、反向地理编码和地理围栏等功能在 Quest 上不可用。请使用 ExpoHorizon.isHorizonDevice 或 ExpoHorizon.isHorizonBuild 保护这些调用。

• 推送通知需要 horizonAppId。 若未设置该值，getDevicePushTokenAsync 在 Quest 设备上将无法返回有效令牌。在 Quest 上使用 getDevicePushTokenAsync（而非 getExpoPushTokenAsync）；将返回的 { type: 'horizon', data } 令牌发送到你的后端，并通过 Meta 的推送服务发送通知。

• isHorizonDevice 与 isHorizonBuild。 使用 isHorizonDevice 检查运行时硬件（检测实体 Quest 设备）。使用 isHorizonBuild 进行构建时功能门控（检查编译进了哪些原生代码）。

• 不支持 Expo Go。 你必须通过 npx expo prebuild 使用自定义开发构建。

官方参考资料

如果 HTML 页面无法呈现源内容，请始终使用 webfetch 获取原始 Markdown（raw.githubusercontent.com/...）；原始 URL 才是权威来源。

主题	官方来源
仓库概览和软件包列表	expo-horizon README
安装、配置插件选项、运行时 API、原生模块访问	expo-horizon-core README
位置迁移、限制、功能支持矩阵	expo-horizon-location README
推送通知迁移、令牌类型、功能支持矩阵	expo-horizon-notifications README
三个软件包的示例应用接入方式	expo-horizon example README
面板尺寸指南（dp 值、方向、加边框）	Meta 面板尺寸
用于发布的 Meta Horizon Store 清单检查表	发布移动端清单
设备管理、投屏、侧载、ADB	Meta Quest Developer Hub
通过 Meta 推送服务在服务器端发送推送通知	Horizon OS 推送通知