PWA Platform

Vite + Vue 接入 ​

适用范围：Vite 8、Vue 3.4 及以上且低于 4，构建环境为 Node.js 22.12 或更高版本。先按包选择安装，再完成以下步骤。示例以部署在域名根路径为例；若部署到 /app/，需要同时调整 Vite base、身份中的路径和安装资源 URL。

本页的页面入口依赖构建期提供的 virtual:pwa-config。当前插件不支持 vite dev；本地验证请运行生产构建，再用 vite preview 打开产物。

示例使用 App.vue 单文件组件，需要在 Vite 中启用 @vitejs/plugin-vue。已有 Vite + Vue 项目保留原有 Vue 插件；若尚未安装，先运行 pnpm add -D @vitejs/plugin-vue@6.0.9。

1. 声明身份与策略 ​

在项目根目录新增 pwa.config.ts，按配置指南填写真实 origin、名称和图标。生产身份首次注册后不能随意改动。

2. 挂载构建插件 ​

ts
// vite.config.ts
import { pwa } from "@pwa-platform/vite";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { IDENTITY, INSTALL, POLICY } from "./pwa.config";

export default defineConfig({
  base: "/",
  plugins: [
    vue(),
    pwa({
      identity: IDENTITY,
      install: INSTALL,
      policy: POLICY,
      topology: { kind: "standalone-origin" },
      offlinePage: {},
    }),
  ],
});

offlinePage: {} 要与策略中的离线回退及其资源规则一起使用；插件会生成离线页并把 manifest 链接注入 HTML。若项目还有其他 Vite 插件，保留它们，在 plugins 数组中加入 pwa() 即可。

3. 安装 Vue 绑定 ​

ts
// src/main.ts
import config from "virtual:pwa-config";
import { createPwa } from "@pwa-platform/vue";
import { createApp } from "vue";
import App from "./App.vue";

const app = createApp(App);
app.use(createPwa({ config, updateCheck: { intervalMs: 1_800_000 } }));
app.mount("#app");

为虚拟模块增加类型声明：

ts
// src/virtual-pwa.d.ts
declare module "virtual:pwa-config" {
  import type { createPwa } from "@pwa-platform/vue";
  const config: Parameters<typeof createPwa>[0]["config"];
  export default config;
}

4. 在应用启动后注册 ​

vue
<script setup lang="ts">
import { usePwa } from "@pwa-platform/vue";
import { onMounted } from "vue";

const pwa = usePwa();
onMounted(() => {
  void pwa.register();
});
</script>

<template>
  <button v-if="pwa.state.value.installEligible" @click="pwa.promptInstall()">
    安装应用
  </button>
  <button v-if="pwa.state.value.updateWaiting" @click="pwa.applyUpdate()">
    应用更新
  </button>
</template>

上面的按钮仅演示 API。实际更新流程需处理失败、稍后提醒、未保存内容和是否刷新页面，见安装与更新。

5. 构建并验收 ​

运行项目的生产构建，然后把产物部署到与 IDENTITY.origin、scope 一致的 HTTPS 地址。接着按上线前检查确认首次注册、离线重新打开和更新等待行为。