Next.js应用部署Firebase App Hosting与Cloud Functions时的依赖问题

问题背景 #

开发Next.js项目，使用Firebase App Hosting部署，新增Cloud Functions后，单独执行firebase deploy --only functions部署正常，但通过App Hosting全量部署时出现依赖缺失错误，怀疑是App Hosting处理应用与Functions依赖的方式导致冲突。

示例函数代码：

import {onRequest} from "firebase-functions/v2/https";
import * as logger from "firebase-functions/logger";

export const helloWorld = onRequest((request, response) => {
  logger.info("Hello logs!", {structuredData: true});
  response.send("Hello from Firebase!");
});

环境与目录结构 #

• 部署方式：Firebase App Hosting托管Next.js应用，TypeScript编写Cloud Functions
• 应用与functions目录各自独立维护package.json，实现依赖隔离

项目目录结构：

/project_name
├── /app
├── /components
├── /functions
│   ├── /lib
│   ├── /src
│   │   └── index.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── .eslintrc.js
├── /public
├── .firebaserc
├── firebase.json
├── apphosting.yaml
├── .gitignore
├── package.json
├── package-lock.json
├── next.config.js
├── tsconfig.json
├── next.config.mjs

关键配置文件 #

functions/package.json #

{
  "name": "functions",
  "scripts": {
    "lint": "eslint --ext .js,.ts .",
    "build": "tsc",
    "build:watch": "tsc --watch",
    "serve": "npm run build && firebase emulators:start --only functions",
    "shell": "npm run build && firebase functions:shell",
    "start": "npm run shell",
    "deploy": "firebase deploy --only functions",
    "logs": "firebase functions:log"
  },
  "engines": {
    "node": "18"
  },
  "main": "lib/index.js",
  "dependencies": {
    "firebase-admin": "^12.1.0",
    "firebase-functions": "^6.0.1"
  },
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^5.12.0",
    "@typescript-eslint/parser": "^5.12.0",
    "eslint": "^8.9.0",
    "eslint-config-google": "^0.14.0",
    "eslint-plugin-import": "^2.25.4",
    "firebase-functions-test": "^3.1.0",
    "typescript": "^4.9.0"
  },
  "private": true
}

functions/tsconfig.json #

{
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "outDir": "lib",
    "sourceMap": true,
    "strict": true,
    "target": "es2017"
  },
  "compileOnSave": true,
  "include": [
    "src"
  ]
}

firebase.json #

{
  "emulators": {
    "auth": { "port": 9099 },
    "functions": { "port": 5001 },
    "firestore": { "port": 8080 },
    "storage": { "port": 9199 },
    "ui": { "enabled": true },
    "singleProjectMode": true
  },
  "firestore": {
    "rules": "firestore.rules",
    "indexes": "firestore.indexes.json"
  },
  "storage": {
    "rules": "firebasestorage.rules"
  },
  "functions": [
    {
      "source": "functions",
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "*.local"
      ],
      "predeploy": [
        "npm --prefix \"$RESOURCE_DIR\" run lint",
        "npm --prefix \"$RESOURCE_DIR\" run build"
      ]
    }
  ]
}

根目录package.json #

{
  "name": "project_name",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "browser-image-compression": "^2.0.2",
    "dotenv": "^16.4.5",
    "firebase": "^10.13.1",
    "next": "14.2.11",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "eslint": "^8",
    "eslint-config-next": "14.2.11",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "typescript": "^5"
  }
}

已做排查 #

• 确认functions目录独立package.json包含所有必要依赖
• 根目录package.json仅包含Next.js相关依赖，无冗余
• 验证apphosting.yaml环境变量配置正确

问题 #

1. Firebase App Hosting部署Next.js+Cloud Functions并存时是否存在已知依赖冲突问题？
2. 需要遵循哪些Firebase特定步骤，确保App Hosting正确隔离两者的依赖？

解决方案 #

1. 配置App Hosting忽略functions目录 #

在apphosting.yaml中添加忽略规则，避免App Hosting构建过程中扫描functions目录的依赖：

build:
  ignore:
    - functions/**

2. 确保Functions预构建逻辑仅在Functions部署时触发 #

firebase.json中的Functions predeploy脚本默认仅在部署Functions时执行，但若全量部署时出现误触发，可通过明确指定部署目标规避，或在App Hosting构建阶段跳过Functions相关操作。

3. 统一Node.js版本 #

根目录和functions目录的Node.js版本需保持兼容：

• 在根目录package.json中添加engines字段，指定Node.js 18（与functions一致）：

"engines": {
  "node": "18"
}

4. 明确App Hosting构建命令 #

在apphosting.yaml中指定仅执行Next.js的build脚本，避免包含Functions构建操作：

build:
  command: npm run build

5. 清理缓存后重新部署 #

执行以下命令清理本地依赖缓存并强制部署：

rm -rf functions/node_modules && cd functions && npm install && cd ..
firebase deploy --only hosting:app --force

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