升级Node.js 18后Firebase模拟器启动Cloud Functions失败排查

问题重现 #

将Node.js版本从16升级到18后，执行本地模拟器启动命令：

firebase emulators:start --only "functions,auth,firestore"

Cloud Functions模块加载失败，报错如下：

i  functions: Watching "<project-folder>\functions" for Cloud Functions...
+  functions: Using node@18 from host.
!!  functions: Failed to load function definition from source: 
FirebaseError: User code failed to load. Cannot determine backend specification

但云端部署命令firebase deploy --only functions执行完全正常，相关package.json配置如下：

{
  "name": "functions",
  "description": "Cloud Functions for Firebase",
  "scripts": {
    "lint": "eslint .",
    "serve": "firebase emulators:start --only functions",
    "emulate": "firebase emulators:start --only \"functions,auth,firestore\"",
    "shell": "firebase functions:shell",
    "start": "npm run shell",
    "deploy": "firebase deploy --only functions",
    "logs": "firebase functions:log"
  },
  "engines": {
    "node": "18"
  },
  "main": "index.js",
  "dependencies": {
    "firebase-admin": "^11.5.0",
    "firebase-functions": "^4.4.0",
  },
  "devDependencies": {
    "eslint": "^8.15.0",
    "eslint-config-google": "^0.14.0",
    "firebase-functions-test": "^3.0.0"
  },
  "private": true
}

问题原因 #

1. Firebase CLI与firebase-functions版本不兼容
   你使用的firebase-functions为4.4.0版本，该版本已适配Node.js 18，但如果本地Firebase CLI版本过低，模拟器无法正确识别新版本函数库的后端配置规范，从而抛出加载错误。云端部署正常是因为Firebase云端环境已适配对应版本的依赖，不受本地CLI版本限制。

2. package.json语法小问题
   dependencies中最后一个依赖项末尾的多余逗号（"firebase-functions": "^4.4.0",）虽然不会导致部署失败，但在Node.js 18的某些解析场景下可能引发潜在的语法解析问题，间接影响模拟器加载逻辑。

解决步骤 #

1. 升级Firebase CLI到最新版本
   执行全局升级命令：

   npm install -g firebase-tools
   

2. 修复package.json语法错误
   删除dependencies中最后一个依赖的多余逗号，修改后片段如下：

   "dependencies": {
     "firebase-admin": "^11.5.0",
     "firebase-functions": "^4.4.0"
   },
   

3. 重新安装依赖并重启模拟器
   进入functions目录，执行：

   npm install
   firebase emulators:start --only "functions,auth,firestore"
   

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