Quasar CLI with Vite - @quasar/app-vite

配置 PWA

Service Worker

为 Quasar 项目添加 PWA 模式意味着会创建一个新目录：/src-pwa，其中包含 PWA 专属文件：

src-pwa/

# (或 .ts) 管理 Service Worker 的 UI 代码（主线程）

manifest.json

# PWA manifest 文件

package.json

# 用于在 /src-pwa 下直接安装 PWA 专属依赖

sw/

# Service Worker 上下文（WebWorker）

custom-sw.js

# (或 .ts) 可选的自定义 Service Worker 文件（仅 InjectManifest 模式）

tsconfig.json

# 仅 TypeScript - WebWorker lib，作用域限定在 /src-pwa/sw/

你可以自由编辑这些文件。注意以下几点：

register-sw.js 会自动导入到你的应用中（和其他 /src 文件一样）。它注册由 Workbox 创建的 Service Worker，并允许你响应其生命周期事件。生成的 Worker 取决于 quasar.config > pwa > workboxMode 配置。
sw/custom-sw.js 仅在 workbox 插件模式设置为 “InjectManifest” 时才会作为你的 Service Worker 文件（quasar.config file > pwa > workboxMode: ‘InjectManifest’）。否则，Quasar 和 Workbox 会为你创建一个 Service Worker 文件。/src-pwa/sw/ 目录是 WebWorker 上下文，其中的所有代码都运行在 Service Worker 中，而非主线程。
建议仅在生产构建上运行 Lighthouse 测试。

TIP

在处理 Service Worker 文档页面了解更多关于 register-sw.js 以及如何与 Service Worker 交互的内容。

quasar.config 文件

这里是你配置 Workbox 行为和调整 manifest.json 的地方。

pwa: {
  /**
   * Workbox operating mode.
   * @default 'GenerateSW'
   */
  workboxMode?: "GenerateSW" | "InjectManifest";

  /**
   * Generated service worker filename to use (needs to end with .js)
   * @default sw.js
   */
  swFilename?: string;

  /**
   * PWA manifest filename to use on your browser
   * @default manifest.json
   */
  manifestFilename?: string;

  /**
   * Should you need some dynamic changes to the /src-pwa/manifest.json,
   * use this method to do it.
   */
  extendPWAManifestJson?: (
    json: PwaManifestOptions
  ) => void | PwaManifestOptions | Promise<void | PwaManifestOptions>;

  /**
   * Does the PWA manifest tag requires crossorigin auth?
   * @default false
   */
  useCredentialsForManifestTag?: boolean;

  /**
   * Auto inject the PWA meta tags?
   * If using the function form, return HTML tags as one single string.
   * @default true
   */
  injectPWAMetaTags?: boolean | ((injectParam: InjectPWAMetaTagsParams) => string);

  /**
   * Extend the Rolldown config that is used for the custom service worker
   * (if using it through workboxMode: 'InjectManifest').
   *
   * Can be async. Can directly modify the "config" parameter or
   * return a new one that will be merged with the default one.
   */
  extendPWACustomSWConf?: (
    config: RolldownOptions
  ) => void | RolldownOptions | Promise<void | RolldownOptions>;

  /**
   * Extend/configure the Workbox GenerateSW options.
   *
   * Can be async. Can directly modify the "config" parameter or
   * return a new one that will be merged with the default one.
   */
  extendPWAGenerateSWOptions?: (
    config: GenerateSWOptions
  ) => void | GenerateSWOptions | Promise<void | GenerateSWOptions>;

  /**
   * Extend/configure the Workbox InjectManifest options.
   *
   * Can be async. Can directly modify the "config" parameter or
   * return a new one that will be merged with the default one.
   */
  extendPWAInjectManifestOptions?: (
    config: InjectManifestOptions
  ) => void | InjectManifestOptions | Promise<void | InjectManifestOptions>;

  /**
   * Extend the generated `.quasar/tsconfig.pwa-sw.json` file.
   *
   * NOT async! Can directly modify the "tsConfig" parameter or
   * return a new one that will be merged with the default one.
   */
  extendPWASwTsConfig (tsConfig) {
    tsConfig.compilerOptions!.lib!.push('WebWorker.AsyncIterable')
  }
}

sourceFiles: {
  pwaRegisterServiceWorker: 'src-pwa/register-sw',
  pwaServiceWorker: 'src-pwa/sw/custom-sw',
  pwaManifestFile: 'src-pwa/manifest.json',
}

如果你想修改 /src 中 UI 的 Vite 配置：

export default defineConfig(ctx => {
  return {
    build: {
      extendViteConf(viteConf) {
        if (ctx.mode.pwa) {
          // do something with viteConf
          // or return an object to deeply merge with current viteConf
        }
      }
    }
  }
})

更多信息：Workbox。

Adding your own meta tags in index.html

Quasar CLI 会动态地为你的 index.html 添加一些 PWA 相关的 meta 标签。如果你想自定义这些标签，首先在 /quasar.config 文件中禁用此行为：

pwa: {
  injectPWAMetaTags: false
}

然后编辑你的 /index.html 文件。以下是 Quasar CLI 动态注入的实际 meta 标签：

<head>
  <% if (ctx.mode.pwa) { %>
  <meta name="theme-color" content="<%= pwaManifest.theme_color %>" />
  <link
    rel="mask-icon"
    href="icons/safari-pinned-tab.svg"
    color="<%= pwaManifest.theme_color %>"
  />
  <meta name="mobile-web-app-capable" content="yes" />
  <meta name="apple-mobile-web-app-status-bar-style" content="default" />
  <meta name="apple-mobile-web-app-title" content="<%= pwaManifest.name %>" />
  <link rel="apple-touch-icon" href="icons/apple-icon-120x120.png" />
  <link
    rel="apple-touch-icon"
    sizes="152x152"
    href="icons/apple-icon-152x152.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="167x167"
    href="icons/apple-icon-167x167.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="180x180"
    href="icons/apple-icon-180x180.png"
  />
  <% } %>
</head>

注意你可以通过上面的 pwaManifest 访问你的 PWA manifest。

或者，你可以像下面这样给 injectPWAMetaTags 赋值一个函数：

pwa: {
  injectPWAMetaTags ({ pwaManifest, publicPath }) {
    return `<meta name="mobile-web-app-capable" content="yes">`
      + `<meta name="apple-mobile-web-app-status-bar-style" content="default">`
  }
}

Picking Workbox mode

Workbox 有两种工作模式：GenerateSW（默认）和 InjectManifest。

通过 /quasar.config 文件设置你想使用的模式：

pwa: {
  workboxMode: 'GenerateSW',
  extendPWAGenerateSWOptions (cfg) {
    // configure workbox on GenerateSW
  }
}

pwa: {
  workboxMode: 'InjectManifest',
  extendPWAInjectManifestOptions (cfg) {
    // configure workbox on InjectManifest
  }
}

GenerateSW

何时使用 GenerateSW：

You want to precache files.
You have simple runtime configuration needs (e.g. the configuration allows you to define routes and strategies).

何时不使用 GenerateSW：

You want to use other Service Worker features (i.e. Web Push).
You want to import additional scripts or add additional logic.

TIP

请查看 Workbox 网站上此模式可用的 workboxOptions。

InjectManifest

何时使用 InjectManifest：

You want more control over your service worker.
You want to precache files.
You have more complex needs in terms of routing.
You would like to use your service worker with other APIs (e.g. Web Push).

何时不使用 InjectManifest：

You want the easiest path to adding a service worker to your site.

TIPS

If you want to use this mode, you will have to write the service worker (/src-pwa/sw/custom-sw.js) file by yourself.
Please check the available workboxOptions for this mode on Workbox website.

以下代码片段是自定义 Service Worker（/src-pwa/sw/custom-sw.js）的默认代码，它模拟了 generateSW 模式的行为：

custom-sw.js

custom-sw.ts

/*
 * This file (which will be your service worker)
 * is picked up by the build system ONLY if
 * quasar.config file > pwa > workboxMode is set to "InjectManifest"
 */

import { clientsClaim } from 'workbox-core'
import { NavigationRoute, registerRoute } from 'workbox-routing'
import {
  cleanupOutdatedCaches,
  createHandlerBoundToURL,
  precacheAndRoute
} from 'workbox-precaching'

self.skipWaiting()
clientsClaim()

// Use with precache injection
precacheAndRoute(self.__WB_MANIFEST)

cleanupOutdatedCaches()

if (import.meta.env.QUASAR_PROD) {
  // Non-SSR/SSG fallbacks to index.html
  // Production SSR/SSG fallbacks to offline.html (except for dev)
  registerRoute(
    new NavigationRoute(
      createHandlerBoundToURL(import.meta.env.QUASAR_PWA_FALLBACK_HTML),
      {
        denylist: [
          new RegExp(import.meta.env.QUASAR_PWA_SERVICE_WORKER_REGEX),
          /workbox-(.)*\.js$/
        ]
      }
    )
  )
}

Configuring Manifest File

Manifest 文件位于 /src-pwa/manifest.json，你可以自由编辑它。

如果你需要在构建时动态修改它，可以编辑 /quasar.config 文件：

pwa: {
  extendPWAManifestJson (json) {
    // tamper with the json inline
  }
}

在深入之前请先阅读 manifest 配置。

WARNING

注意你不需要编辑 index.html 文件（从 /index.html 生成）来链接 manifest 文件。Quasar CLI 会为你处理好一切。

TIP

如果你的 PWA 在基本认证后面或需要 Authorization 头，请将 quasar.config file > pwa > useCredentialsForManifestTag 设置为 true，以在 manifest.json meta 标签上包含 crossorigin="use-credentials"。

PWA Checklist

更多信息：PWA 检查清单

WARNING

Do not run Lighthouse on your development build because at this stage the code is intentionally not optimized and contains embedded source maps (among many other things). See the Testing and Auditing section of these docs for more information.

Reload & Update Automatically

For those who don’t want to manually reload the page when the service worker is updated and are using the default generateSW workbox mode, Quasar CLI has configured Workbox to activate it at once. Should you need to disable this behavior:

pwa: {
  extendPWAGenerateSWOptions (cfg) {
    cfg.skipWaiting = false
    cfg.clientsClaim = false
  }
}

Filename hashes quirk

由于 Rolldown（通过 Vite）构建资源的方式，当你更改任何脚本源文件（.js）时，（几乎）所有 .js 文件的哈希部分都会随之改变（例如 assets/index.454d87bd.js 中的 454d87bd）。所有资源的修订号都会在 service worker 文件中改变，这意味着当 PWA 更新时，它会再次重新下载你的所有资源。

默认情况下，Vite 构建的所有文件名都带哈希部分。如果你希望文件名不包含哈希部分，从而只重新下载变更过的文件，请编辑 /quasar.config 文件：

build: {
  useFilenameHashes: false // true by default
}

此后有两点需要注意：

把这些文件的 webserver 缓存配置得尽可能低（它们跨部署保持相同的名称），以确保那些无法使用 PWA 功能的访客获得一致的资源。
Safari 会把页面预加载（通过 <link rel="modulepreload">）的脚本保存在内存缓存中，并在 service worker 更新后的那次重新加载中复用它们，而不询问 service worker。在文件名稳定的情况下，重新加载的页面会把新的入口文件与旧的 chunk 一起运行，并以 SyntaxError: Importing binding name '...' is not found. 报错，导致该标签页每次重新加载都是空白页面。因此，在页面为应用更新而重新加载之前，以及在新 worker 接管的每个打开的标签页中，都要通过新 worker 获取预缓存的脚本；对某个 URL 执行一次 fetch() 就会驱逐它的陈旧缓存条目：

navigator.serviceWorker.addEventListener('controllerchange', async () => {
  // （首次安装时跳过，此时不可能存在任何陈旧内容）
  const urls = []

  for (const name of await caches.keys()) {
    if (!name.includes('precache')) continue

    const cache = await caches.open(name)
    for (const req of await cache.keys()) {
      const url = req.url.split('?')[0]
      if (url.endsWith('.js')) urls.push(url)
    }
  }

  await Promise.allSettled(
    urls.map(url => fetch(url).then(res => res.body?.cancel()))
  )

  window.location.reload()
})

quasar.dev 网站自己就是这么做的（Quasar 仓库中的 docs/src-pwa/register-sw.js），并使用一个处于等待状态的 service worker（skipWaiting: false），以便只在用户主动请求时才应用更新。

Caught a mistake?Edit this page in browser