使用Quartz SSG部署Firebase Hosting本地预览异常求助

问题概述 #

使用Quartz SSG搭建的站点，本地执行npx quartz build -d docs --serve运行正常，但通过firebase serve --only hosting预览时，出现404错误或页面跳转回首页的异常。

复现步骤 #

git clone https://github.com/jackyzha0/quartz.git
npm install
npx quartz build -d docs --serve  # 本地运行正常
npx quartz build -d docs    
firebase init
firebase serve --only hosting     # 出现异常

Firebase初始化关键配置选择：

• 关联现有Firebase项目
• 公共目录设置为public
• 不配置为单页应用
• 不启用GitHub自动构建部署
• 保留已存在的public/404.html和public/index.html

默认生成的firebase.json：

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  }
}

系统环境：

• Windows 11 Pro
• Node.js: v22.11.0
• Firebase CLI: 13.24.2

已解决Node 22与Firebase CLI的兼容问题，现需确认Quartz是否支持Firebase Hosting。

问题原因 #

1. 构建目录不匹配：Quartz的构建产物输出到docs目录，但Firebase Hosting默认指向public目录，导致Firebase无法加载正确的静态资源。
2. 路由规则缺失：Quartz采用客户端路由机制，Firebase未配置对应重写规则时，非根路径请求会触发404或默认跳转。

解决方案 #

1. 修正Firebase公共目录配置 #

编辑firebase.json，将public字段修改为Quartz的构建输出目录docs：

{
  "hosting": {
    "public": "docs",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  }
}

2. 添加路由重写规则 #

针对Quartz的客户端路由，配置重写规则确保所有非静态资源请求都指向index.html，同时保留静态文件的正常访问：

{
  "hosting": {
    "public": "docs",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html",
        "condition": {
          "not": {
            "or": [
              { "source": "**/*.{js,css,png,jpg,gif,svg,ico}" },
              { "source": "/robots.txt" },
              { "source": "/sitemap.xml" }
            ]
          }
        }
      }
    ]
  }
}

3. 重新构建并预览 #

重新执行Quartz构建，确保产物输出到docs目录：

npx quartz build -d docs

启动Firebase预览验证：

firebase serve --only hosting

关于Quartz对Firebase的支持说明 #

Quartz完全支持Firebase Hosting。Quartz是静态站点生成器，输出的是标准静态资源文件（HTML、CSS、JS、媒体文件等），完全符合Firebase Hosting的部署要求。本次问题仅为配置不匹配导致，并非Quartz与Firebase存在兼容性问题。

内容的提问来源于stack exchange，提问作者Sushanth Bobby Lloyds