Firebase部署、模拟器启动及GitHub流水线均遇Web框架检测错误

问题现象 #

执行firebase deploy部署Angular应用、firebase emulators:start启动本地模拟器，或是GitHub合并触发自动部署流水线时，均抛出相同错误：

Could not determine the web framework in use.
Error: Unable to detect the web framework in use, check firebase-debug.log for more info.

已尝试重新登录Firebase CLI、重新运行firebase init，均未解决问题。

现有配置文件 #

firebase.json #

{
  "firestore": {
    "rules": "firestore.rules",
    "indexes": "firestore.indexes.json"
  },
  "hosting": {
    "source": "dist",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "frameworksBackend": {
      "region": "europe-west1"
    }
  },
  "storage": {
    "rules": "storage.rules"
  },
  "emulators": {
    "auth": {
      "port": 9099
    },
    "firestore": {
      "port": 8080
    },
    "hosting": {
      "port": 5000
    },
    "storage": {
      "port": 9199
    },
    "ui": {
      "enabled": true
    },
    "singleProjectMode": true
  }
}

.firebaserc #

{
  "projects": {
    "default": "mySite-31783"
  },
  "targets": {
    "mySite-31783": {
      "hosting": {
        "mySite": [
          "mySite-31783"
        ]
      }
    }
  }
}

package.json #

{
  "name": "mySite",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test"
  },
  "private": true,
  "dependencies": {
    "@angular/animations": "^16.2.0",
    "@angular/cdk": "^16.2.7",
    "@angular/common": "^16.2.0",
    "@angular/compiler": "^16.2.0",
    "@angular/core": "^16.2.0",
    "@angular/fire": "^7.6.1",
    "@angular/flex-layout": "^15.0.0-beta.42",
    "@angular/forms": "^16.2.0",
    "@angular/material": "^16.2.7",
    "@angular/platform-browser": "^16.2.0",
    "@angular/platform-browser-dynamic": "^16.2.0",
    "@angular/router": "^16.2.0",
    "firebase": "^10.5.0",
    "rxjs": "~7.8.0",
    "tslib": "^2.3.0",
    "zone.js": "~0.13.0"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^16.2.5",
    "@angular/cli": "^16.2.5",
    "@angular/compiler-cli": "^16.2.0",
    "@types/jasmine": "~4.3.0",
    "jasmine-core": "~4.6.0",
    "karma": "~6.4.0",
    "karma-chrome-launcher": "~3.2.0",
    "karma-coverage": "~2.2.0",
    "karma-jasmine": "~5.1.0",
    "karma-jasmine-html-reporter": "~2.1.0",
    "typescript": "~5.1.3"
  }
}

解决方案 #

1. 移除不必要的frameworksBackend配置 #

frameworksBackend是为服务端渲染（SSR）框架设计的，Angular作为纯静态编译框架无需该配置。修改firebase.json的hosting节点，删除整个frameworksBackend块：

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

2. 指定完整的编译输出目录 #

Angular执行ng build后，默认将编译产物输出到dist/项目名（此处为dist/mySite），而非直接的dist根目录。修改firebase.json中的source路径：

"hosting": {
  "source": "dist/mySite",
  // 其他配置不变
}

3. 强制指定框架类型（可选） #

若自动检测仍失败，可在hosting配置中手动指定框架类型，跳过自动检测：

"hosting": {
  "source": "dist/mySite",
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ],
  "frameworks": {
    "name": "angular"
  }
}

4. 降级Firebase CLI版本（若为版本兼容问题） #

部分新版本Firebase CLI的框架检测逻辑存在bug，可降级到稳定版本：

npm install -g firebase-tools@11.31.0

验证步骤 #

1. 执行ng build确认编译产物生成在正确目录下
2. 运行firebase deploy --only hosting测试单独部署主机服务
3. 启动模拟器firebase emulators:start --only hosting验证本地运行正常

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