混合 SSG + 部分 CSR | Quasar Framework

Quasar CLI with Vite - @quasar/app-vite

混合 SSG + 部分 CSR

警告！Beta 阶段

Quasar SSG 模式目前处于 “beta” 阶段。根据社区反馈，API 在未来可能会有所变动，因此每次升级 “@quasar/app-vite” 时请留意 release notes。

混合 SSG 让大部分路由使用预渲染的 HTML，而选定的路由则表现得像 SPA 中的页面。这对需要认证的仪表板、账户设置或其他初始内容仅在浏览器中才有意义的页面非常有用。

配置

以下选项在 /quasar.config 的 ssg 配置节中生成：

ssg: {
  /**
   * 配置混合 SSG + 部分 CSR（客户端渲染）构建，
   * 让客户端对某些页面使用空壳 html（就像这些页面属于 SPA），
   * 由客户端代码接管并渲染页面。
   *
   * 仅用于生产环境。您需要正确配置 Web 服务器，
   * 对未被 SSG 预渲染的页面回退到此 html 文件。
   *
   * 确保命名不会与 SSG 生成的 html 文件冲突！
   *
   * 如果构建的是 SSG+PWA 应用，可以直接使用
   * `pwaOfflineHtmlFilename` 作为空壳 html 文件，
   * 因为它们的内容相同。否则请使用不同的名称，
   * 以免与 `pwaOfflineHtmlFilename` 冲突！
   *
   * 如果未显式配置且 `clientSideRenderingRoutes`
   * 不是默认值（空数组），则此选项默认为 'csr.html'。
   *
   * @default false | 'csr.html'
   */
  clientSideRenderingHtmlFilename?: string | false;

  /**
   * 配置混合 SSG + 部分 CSR（客户端渲染）方案，
   * 指定哪些 Vue Router 路由仅在客户端渲染。
   *
   * 如果未同时指定 `clientSideRenderingHtmlFilename`，
   * 其默认值将变为 'csr.html'。
   *
   * 在生产环境中，您需要正确配置 Web 服务器，
   * 对未被 SSG 预渲染的页面回退到
   * `clientSideRenderingHtmlFilename`。
   *
   * 可以使用 picomatch 模式来匹配要在客户端渲染的路由。
   * https://www.npmjs.com/package/picomatch
   *
   * picomatch 模式说明：
   *   "/admin" 仅匹配该精确路由
   *   "/admin/**" 匹配该精确路由及 /admin 的所有子路由
   *   "/admin/*" 仅匹配 /admin 的直接子路由
   *   "/admin/{users,settings}" 匹配 /admin/users 和 /admin/settings 两个精确路由
   *
   * @example ['/dashboard', '/admin/**']
   * @default []
   */
  clientSideRenderingRoutes?: string[];
}

例如，以下配置在客户端渲染账户路由，并将外壳写入 dist/ssg/app-shell.html：

ssg: {
  clientSideRenderingHtmlFilename: 'app-shell.html',

  /**
   * 排除这些路由的预渲染，并生成 csr.html
   * picomatch 模式说明：
   *   "/admin" 仅匹配该精确路由
   *   "/admin/**" 匹配该精确路由及 /admin 的所有子路由
   *   "/admin/*" 仅匹配 /admin 的直接子路由
   *   "/admin/{users,settings}" 匹配 /admin/users 和 /admin/settings 两个精确路由
   */
  clientSideRenderingRoutes: ['/account{,/**}', '/admin']
}

不要使用可能被 SSG 页面同名产生的文件名。设置 clientSideRenderingHtmlFilename: false 即使配置了路由模式也会禁用外壳生成。

工作原理

开发时，匹配的路由绕过服务端渲染，使用客户端应用外壳。
生产构建时，parseVueRouterRoutes() 从生成页面列表中排除匹配的路由（但会将它们添加到返回对象的 ignoredCsrSsgPages 中）。
生产构建写入一个 CSR 外壳文件。您的静态主机必须将每个匹配的请求重写到该文件，而不改变浏览器 URL。

使用上述配置，对 /account/profile 和 /account/security 的请求都必须提供 /app-shell.html。不要将每个缺失 URL 都重写到 CSR 外壳，因为那会把真正找不到的请求变成客户端渲染的页面。

有关 nginx 和静态主机示例，请参阅部署 SSG。

SSG + PWA

PWA 离线外壳与应用外壳内容相同。您可以将 clientSideRenderingHtmlFilename 设为 pwaOfflineHtmlFilename 的值，这样两个功能共用一个文件。否则两个文件名必须不同。

发现错误？在浏览器中编辑此页

1. Introduction

2. 配置

3. 工作原理