SSG 构建产出一个静态文件目录。您将这些文件部署到静态 Web 服务器或静态托管提供商。生产环境不需要运行 Node.js 渲染器。

与 SPA 部署的重要区别在于，SSG 可以生成许多 html 文件，而不仅仅是一个 index.html。您的主机应优先提供这些生成的文件，然后再应用您明确需要的任何客户端回退规则。

构建产物

以 SSG 模式构建应用：

quasar build -m ssg

默认输出目录为：

dist/ssg

部署 dist/ssg 的内容，而不是该文件夹本身，除非您的主机要求指定发布目录。

例如，当一个路由被渲染为 /guide/install 时，生成的文件通常写入：

dist/ssg/guide/install/index.html

支持目录索引的静态主机可以为 /guide/install 或 /guide/install/ 提供该文件。

静态主机配置清单

配置主机时按此顺序：

1. 优先提供已有文件和已生成的路由目录。
2. 对哈希化的资源（如 JavaScript、CSS、字体和图片）设置长期缓存头。
3. 对 html 文件设置较短或不缓存的策略，特别是频繁更新部署时。
4. 如果使用混合 SSG + 部分 CSR，将指定的客户端渲染路由重写到 CSR 外壳文件。
5. 对真正找不到的请求提供生成的 404.html 文件。

避免复制通常的 SPA 规则——将每个未知请求重写到 index.html。这会隐藏缺失的生成页面，并可能让预渲染的 SSG 站点表现得像普通 SPA。

404 页面

默认情况下，Quasar 生成：

dist/ssg/404.html

配置您的主机在请求不匹配已生成文件或静态资源时提供此文件。

您可以通过 /quasar.config 中的 ssg.error404HtmlFilename 更改或禁用此文件名：

export default defineConfig(() => {
  return {
    ssg: {
      error404HtmlFilename: '404.html'
    }
  }
})

一些主机自动使用根目录下的 404.html 文件。其他主机需要显式的 error_page、重写或回退规则。

混合 SSG + 部分 CSR

如果配置了 ssg.clientSideRenderingRoutes，Quasar 可以为仅在客户端渲染的路由生成单独的 html 外壳：

export default defineConfig(() => {
  return {
    ssg: {
      clientSideRenderingHtmlFilename: 'csr.html',

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

在这种配置下，配置主机仅将这些路由模式重写到：

dist/ssg/csr.html

不要将 csr.html 用作每个未知 URL 的回退，除非您有意让不匹配的路由变成客户端渲染页面。对真正找不到的请求保留 404.html。

示例

示例：nginx

此示例优先提供生成的 SSG 文件，仅对 /dashboard 和 /admin 使用 CSR 外壳，其他缺失文件使用 404.html：

server {
    listen 80;
    server_name example.com;

    root /var/www/example.com/dist/ssg;
    index index.html;

    location = /dashboard {
        try_files $uri $uri/ /csr.html;
    }

    location ^~ /dashboard/ {
        try_files $uri $uri/ /csr.html;
    }

    location = /admin {
        try_files $uri $uri/ /csr.html;
    }

    location ^~ /admin/ {
        try_files $uri $uri/ /csr.html;
    }

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

如果您的站点不使用混合 CSR 路由，删除 /dashboard 和 /admin 块即可。

示例：Netlify

将发布目录设置为：

dist/ssg

对于完全预渲染的 SSG 站点，生成的文件和根目录下的 404.html 就够了。Netlify 会自动为不匹配静态文件的请求提供根目录下的 404.html。

对于混合 CSR 路由，在 /public 中添加 _redirects 文件。Quasar 会将其复制到输出目录根目录：

/dashboard    /csr.html  200
/dashboard/*  /csr.html  200
/admin        /csr.html  200
/admin/*      /csr.html  200

Netlify 在应用这些非强制重写之前会先提供已有的静态文件。您不需要为 404.html 添加兜底规则。

根据您的 ssg.clientSideRenderingRoutes 配置调整路由模式。更多选项请参阅 Netlify 重定向文档。

示例：Cloudflare Pages

将构建输出目录设置为：

dist/ssg

Cloudflare Pages 会提供匹配的 html 文件，并自动为未找到的请求使用根目录下的 404.html。404.html 的存在很重要，因为没有它的话，Cloudflare Pages 会假设站点是 SPA 并应用自动 SPA 回退。

对于混合 CSR 路由，在 /public/_redirects 中添加相同的路由代理规则：

/dashboard    /csr.html  200
/dashboard/*  /csr.html  200
/admin        /csr.html  200
/admin/*      /csr.html  200

Cloudflare Pages 在匹配静态文件之前应用 _redirects 规则。确保这些模式仅匹配您有意从 SSG 渲染中排除的路由。不要添加指向 csr.html 的兜底代理。

有关 重定向 和 未找到行为 的详细信息，请参阅 Cloudflare Pages 文档。

示例：Vercel

将输出目录设置为：

dist/ssg

对于完全预渲染的 SSG 站点，Vercel 可以直接提供生成的静态文件。

对于混合 CSR 路由，仅为这些路由添加重写规则：

{
  "rewrites": [
    { "source": "/dashboard", "destination": "/csr.html" },
    { "source": "/dashboard/:path*", "destination": "/csr.html" },
    { "source": "/admin", "destination": "/csr.html" },
    { "source": "/admin/:path*", "destination": "/csr.html" }
  ]
}

当没有其他静态文件或路由匹配时，Vercel 会自动从输出目录提供 404.html。更多路由选项请参阅 Vercel 重写文档。

示例：GitHub Pages

GitHub Pages 最适合完全预渲染的 SSG 站点：

1. 使用 quasar build -m ssg 构建。
2. 发布 dist/ssg 的内容。
3. 保持生成的 404.html 在发布输出的根目录。

GitHub Pages 不提供像 nginx、Netlify、Cloudflare Pages 或 Vercel 那样的路径特定重写规则。如果您的应用依赖混合 CSR 回退（如 /admin/** -> /csr.html），请选择支持重写的主机，或将这些路由纳入 SSG 页面生成列表。

对于项目站点（如 https://username.github.io/repository/），构建前还需设置 build.publicPath 为 /repository/。

SSG 配合 PWA

当启用 ssg.pwa 时，Quasar 还会生成 service worker 资源和离线外壳，通常为：

dist/ssg/offline.html

部署整个 dist/ssg 目录，包括 service worker 和 manifest 资源。确保您的主机不会将 service worker 文件、web manifest、图标或生成的 Workbox 资源重写到另一个 html 文件。

有关 SSG 特定的 PWA 选项，请参阅 SSG 配合 PWA。

部署在子目录下

如果站点从子目录提供，构建前配置公共路径：

export default defineConfig(() => {
  return {
    build: {
      publicPath: '/docs/'
    }
  }
})

然后配置主机使生成的文件从相同的基础路径提供。直接在浏览器中测试深层链接，而不是仅从首页通过客户端导航测试。

缓存头

确切的语法和提供商默认值各不相同，但对于自管理服务器，一个好的起点是：

• Html 文件：Cache-Control: no-cache
• 哈希化资源：Cache-Control: public, max-age=31536000, immutable
• Service worker 文件：遵循 PWA 部署指南 的建议

不要允许过期的 html 文件在新部署后仍被缓存。否则浏览器可能加载指向服务器上已不存在的资源的旧 html。

托管主机可能已提供部署感知的缓存。在覆盖之前检查主机的默认值。例如，Cloudflare Pages 推荐对大多数站点使用其默认缓存行为，并通过 /public/_headers 文件支持自定义浏览器头。

最终验证

部署后，在全新的浏览器标签页中直接打开几个 URL：

• /
• 一个生成的嵌套路由，如 /guide/install
• 一个应显示 404.html 的不存在路由
• 一个混合 CSR 路由（如果配置了的话）
• 在客户端导航后刷新一个已生成的路由

如果这些直接请求正常工作，说明静态主机正确提供了 SSG 产物。