升级Angular v19混合渲染后，Firebase部署在Cloud Build中失败

背景信息 #

• 原有环境：Angular SSR v18部署于Firebase App Hosting，GitHub提交自动触发Google Cloud Build构建部署，此前运行正常
• 升级至Angular v19后，实现混合渲染及服务端路由（代码如下），同时在angular.json的build选项中配置"outputMode": "server"

// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';
export const serverRoutes: ServerRoute[] = [
  { path: '', renderMode: RenderMode.Client },
  { path: 'about', renderMode: RenderMode.Prerender },
  { path: 'contact', renderMode: RenderMode.Prerender },
  { path: 'help', renderMode: RenderMode.Prerender },
  { path: 'privacy', renderMode: RenderMode.Prerender },
  { path: 'terms', renderMode: RenderMode.Prerender },
  { path: '**', renderMode: RenderMode.Server },
];

• 本地执行ng build无异常，dist目录生成prerendered-routes.json：

// prerendered-routes.json
{
  "routes": {
    "/about": {},
    "/contact": {},
    "/help": {},
    "/privacy": {},
    "/terms": {}
  }
}

报错情况 #

上传至GitHub触发Cloud Build时构建失败，核心报错：

ZodError: [
  {
    "code": "invalid_type",
    "expected": "array",
    "received": "object",
    "path": ["prerenderedRoutes"],
    "message": "Expected array, received object"
  }
]

即使移除所有预渲染路由，prerenderedRoutes为空对象时仍报相同错误。

解决建议 #

1. 更新Firebase相关依赖版本 #

Angular 19对预渲染路由的输出格式做了调整（从数组改为对象结构），但Cloud Build使用的Firebase构建工具（如@angular/fire或官方构建镜像）可能未适配该变化。

• 本地项目执行npm install @angular/fire@latest更新到兼容Angular 19的版本
• 在Cloud Build配置文件（cloudbuild.yaml）中，确保使用最新的Firebase Node.js构建镜像，或在构建步骤中强制安装最新依赖（避免缓存旧版本）

2. 手动转换预渲染路由格式 #

若暂时无法更新依赖，可在Cloud Build步骤中添加脚本，将Angular 19输出的对象格式路由转为工具期望的数组格式：

1. 在项目根目录创建转换脚本convert-prerender-routes.js：

const fs = require('fs');
const path = require('path');

const routesFile = path.join(__dirname, 'dist/vogel-bazaar/prerendered-routes.json');
const routesData = JSON.parse(fs.readFileSync(routesFile, 'utf8'));

// 将对象转为路由字符串数组
routesData.routes = Object.keys(routesData.routes);
fs.writeFileSync(routesFile, JSON.stringify(routesData));

2. 在Cloud Build的构建步骤中，添加执行该脚本的命令（放在ng build之后）：

node convert-prerender-routes.js

3. 清理Cloud Build缓存 #

旧的缓存可能残留了不兼容的依赖或构建产物，导致报错。可在Cloud Build配置中添加清理步骤，或手动触发构建时勾选"禁用缓存"选项。

4. 调整Angular构建配置 #

尝试修改angular.json中的prerender相关配置，强制输出数组格式的路由：

• 在projects.[your-project].architect.prerender配置中，添加"routesOutput": "array"（若Angular 19支持该参数）
• 暂时切换outputMode为"hybrid"测试是否兼容，再逐步调整回"server"模式

内容的提问来源于stack exchange，提问作者ChrisWF