跳到主要内容

webspatial-builder run

用于在模拟器中预览 Packaged WebSpatial App。 它会自动完成打包、启动模拟器、把应用包传进模拟器、安装并启动应用。

Quick Reference​

项目内容
最适合在模拟器里预览 Packaged WebSpatial App。
是否需要真机凭证不需要。
常见目标平台没有内置 WebSpatial Runtime 的平台，比如 visionOS。

适用场景​

不适用场景​

语法​

在模拟器中预览 Packaged WebSpatial App
webspatial-builder run \
  [--base=<base url>] \
  [--manifest=<local path>] \
  [--manifest-url=<url>] \
  [--project=<dist>]

选项总览​

选项是否必填作用
--base可选提供或覆盖用于解析 start_url 的 base URL。
--manifest可选指定本地 Web App Manifest 文件路径。
--manifest-url可选直接从线上 URL 获取 Manifest。
--project可选指定自定义的网站构建产物目录。

选项​

--base​

为当前 Web App 的起始网址（start_url）指定 base URL。默认值是 ""。

如果 WebSpatial Builder 不知道当前 Web App 的 start_url，--base 的值会被直接作为 start_url。

如果 WebSpatial Builder 获取到的 start_url 是相对地址，缺少域名部分，可以通过 --base 提供域名，补全 URL。

解析状态运行时行为
已有完整的 start_urlPackaged App 在运行过程中会从线上加载 HTML/CSS/JS 等 Web 文件。
缺少完整的 start_urlWebSpatial Builder 会把网站构建产物打包进原生应用包里，运行时从应用包内的本地文件离线加载网站内容。
开发阶段优先提供 --base

在开发调试阶段，离线打包模式会导致每次代码修改后都要重新运行 Builder，并等待打包和安装完成。只要条件允许，都建议提供 --base。

如果 WebSpatial Builder 已经拿到当前 Web App 的完整 start_url，可以用 --base 修改 start_url 的 base 部分。

--manifest​

让 WebSpatial Builder 知道从当前项目的什么路径读取 Web App Manifest 文件。默认会从 public/manifest.webmanifest 或 public/manifest.json 读取。

run 的临时 Manifest

run 命令在找不到 manifest 时，会使用下面这份临时 manifest，以减少项目早期接入时的准备工作：

run 使用的临时 manifest
{
  name: "WebSpatialTest",
  display: "minimal-ui",
  start_url: "/",
  scope: "/",
}

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 从其他路径读取网站构建产物。