webspatial-builder build
用于在测试设备上预览 Packaged WebSpatial App。 它只负责打包；你仍然需要使用平台官方工具（比如 Xcode）把应用包推送到测试设备、完成安装并启动。 visionOS 测试设备需要事先在 Apple 开发者账号控制台和 Xcode 中注册。
Quick Reference
| 项目 | 内容 |
|---|---|
| 最适合 | 在个人测试设备上预览 Packaged WebSpatial App。 |
| 必填凭证 | 在 visionOS 上需要 --bundle-id 和 --teamId。 |
| 是否上传到应用商店 | 不会。 |
适用场景
- 要在不包含 WebSpatial Runtime 的空间计算平台（比如 visionOS）上运行 WebSpatial App。
- 只需要在个人测试设备上预览效果。
不适用场景
- 要在内置了 WebSpatial Runtime、支持直接用 URL 运行 WebSpatial App 的空间计算平台上运行，比如 PICO OS 6。
- 只需要在模拟器里预览，或要对外大量分发应用。
语法
webspatial-builder build \
--bundle-id=<id> \
--teamId=<id> \
[--export=<local path>] \
[--base=<base url>] \
[--manifest=<local path>] \
[--manifest-url=<url>] \
[--project=<dist>]
选项总览
| 选项 | 是否必填 | 作用 |
|---|---|---|
--teamId | visionOS 必填 | 指定用于签名构建结果的 Apple 开发团队。 |
--bundle-id | visionOS 必填 | 指定已注册的 Apple 应用标识符。 |
--export | 可选 | 修改原生应用包的导出路径。 |
--base | 可选 | 提供或覆盖用于解析 start_url 的 base URL。 |
--manifest | 可选 | 指定本地 Web App Manifest 文件路径。 |
--manifest-url | 可选 | 直接从线上 URL 获取 Manifest。 |
--project | 可选 | 指定自定义的网站构建产物目录。 |
选项
--teamId
在 visionOS 设备上预览效果时必填，值来自 Apple 开发者账号控制台开发者信息中的 Team ID。
--bundle-id
在 visionOS 设备上预览效果时必填，值来自在 Apple 开发者账号控制台注册 App 后得到的 Bundle ID。
--export
WebSpatial Builder 生成的原生应用包默认会写入 build/ 目录，可以用 --export 改成自定义路径。
--base
为当前 Web App 的起始网址（start_url）指定 base URL。默认值是 ""。
如果 WebSpatial Builder 不知道当前 Web App 的 start_url，--base 的值会被直接作为 start_url。
如果 WebSpatial Builder 获取到的 start_url 是相对地址，缺少域名部分，可以通过 --base 提供域名，补全 URL。
| 解析状态 | 运行时行为 |
|---|---|
已有完整的 start_url | Packaged App 在运行过程中会从线上加载 HTML/CSS/JS 等 Web 文件。 |
缺少完整的 start_url | WebSpatial Builder 会把网站构建产物打包进原生应用包里，运行时从应用包内的本地文件离线加载网站内容。 |
如果 WebSpatial Builder 已经拿到当前 Web App 的完整 start_url，可以用 --base 修改 start_url 的 base 部分。
--manifest
让 WebSpatial Builder 知道从当前项目的什么路径读取 Web App Manifest 文件。默认会从 public/manifest.webmanifest 或 public/manifest.json 读取。
Web App Manifest 里的 start_url 等字段通常都是相对地址，不会写死域名等 base URL 信息，所以 WebSpatial Builder 仅凭仓库里的 manifest 文件无法确定如何通过 URL 访问当前 Web App，需要依靠 --base 获取域名并补全 URL。否则生成的 Packaged App 会包含所有网站构建产物，而不是从线上加载网站。
--manifest-url
让 WebSpatial Builder 直接通过 URL 获取线上网站中的 Web App Manifest。
由于这个 URL 自带域名等 base 信息，即使 Manifest 文件中的 start_url 是相对地址，WebSpatial Builder 也可以像浏览器一样自动推导并补全 start_url。在这种情况下，Builder 相当于直接把线上的 Web App 以 URL 形式嵌入 Packaged App，不再需要本地项目文件，也不再依赖 --base 等参数。
--project
如果 WebSpatial Builder 无法确定如何通过 URL 访问当前 Web App，默认会从 dist/ 读取网站构建产物并打包进原生应用包里。
可以用 --project 让 WebSpatial Builder 从其他路径读取网站构建产物。