Firebase Tools 部署 NextJS 应用时出现 404 页面问题的分析与解决方案

问题背景

Firebase Tools 作为 Firebase 生态中的核心命令行工具，在最新版本 13.32.0 中引入了一个影响 NextJS 应用部署的严重问题。许多开发者报告，在使用该版本部署 NextJS 应用时，网站会直接显示 404 页面，而之前版本则工作正常。

问题现象

开发者在使用 Firebase Tools 13.32.0 版本部署 NextJS 应用时，主要观察到以下异常现象：

1. 部署时间异常缩短：从正常的7分钟左右骤降至30秒左右
2. 部署后访问网站直接显示404页面
3. 部署日志中没有明显的错误信息
4. 问题主要出现在使用 GitHub Actions 自动化部署的场景中

问题根源

经过 Firebase 团队和社区开发者的深入调查，发现问题源于以下两个关键因素：

1. 配置方式差异：当 firebase.json 中使用 site 字段而非 target 字段配置托管站点时，部署流程会异常终止
2. 数组处理逻辑缺陷：在检查是否为 Web 框架部署时，代码错误地使用了 array.find 而非 array.some，导致对于配置数组中第二个及以后的站点会错误判断

临时解决方案

在官方修复版本发布前，开发者可以采用以下临时解决方案：

1. 降级 Firebase Tools 版本：

npm install -g firebase-tools@13.31.2

2. 在 GitHub Actions 中指定版本：

- uses: FirebaseExtended/action-hosting-deploy@v0
  with:
    firebaseToolsVersion: "13.31.2"

3. 修改配置方式：将 site 改为 target 配置方式

官方修复

Firebase 团队迅速响应，通过两个PR解决了该问题：

1. 初步修复了 site 配置方式的问题
2. 后续修复了数组处理逻辑的缺陷

这些修复已包含在 Firebase Tools 13.34.0 及更高版本中。

最佳实践建议

为避免类似问题，建议开发者：

1. 使用 target 而非 site 进行多环境配置
2. 在 CI/CD 流程中固定 Firebase Tools 版本
3. 部署前检查构建产物是否完整
4. 对于关键业务部署，先在测试环境验证新版本

总结

这次事件展示了开源社区协作解决问题的典型流程：用户报告问题、开发者重现问题、团队分析原因、社区提供临时方案、官方发布修复版本。对于使用 Firebase 托管 NextJS 应用的开发者，建议升级到最新版 Firebase Tools 以获得最稳定的部署体验。