如何修复`firebase deploy --only functions`中的Node版本错误

问题背景 #

• 执行firebase deploy --only functions时触发Node版本不兼容错误
• 本地通过asdf管理Node版本，已安装20.11.0，Firebase CLI版本13.1.0
• package.json配置"engines": { "node": ">=18.5" }，firebase.json设置"runtime": "nodejs20"
• 项目依赖sharp要求Node版本为^18.17.0 || ^20.3.0 || >=21.0.0
• 部署前置lint等步骤均通过，但报错检测到Node 18.5.0（本地未安装该版本），因sharp要求最低Node版本为18.7.0，目标是配置环境使用Node 20.3.0完成部署

报错输出 #

✔  functions: Finished running predeploy script.
i  functions: preparing codebase typescript for deployment
i  functions: ensuring required API cloudfunctions.googleapis.com is enabled...
i  functions: ensuring required API cloudbuild.googleapis.com is enabled...
i  artifactregistry: ensuring required API artifactregistry.googleapis.com is enabled...
✔  artifactregistry: required API artifactregistry.googleapis.com is enabled
✔  functions: required API cloudfunctions.googleapis.com is enabled
✔  functions: required API cloudbuild.googleapis.com is enabled
i  functions: Loading and analyzing source code for codebase typescript to determine what to deploy
Serving at port 8928

Error: Could not load the "sharp" module using the darwin-x64 runtime
Possible solutions:
- Please upgrade Node.js:
    Found 18.5.0
    Requires ^18.17.0 || ^20.3.0 || >=21.0.0
- Consult the installation documentation:
    See https://sharp.pixelplumbing.com/install
    at Object.<anonymous> (/Users/troy/Projects/field-tracker-admin-console/functions/node_modules/sharp/lib/sharp.js:114:9)
    at Module._compile (node:internal/modules/cjs/loader:1112:14)
    at Module._compile (pkg/prelude/bootstrap.js:1890:32)
    at Module._extensions..js (node:internal/modules/cjs/loader:1166:10)
    at Module.load (node:internal/modules/cjs/loader:988:32)
    at Module._load (node:internal/modules/cjs/loader:834:12)
    at Module.require (node:internal/modules/cjs/loader:1012:19)
    at Module.require (pkg/prelude/bootstrap.js:1851:31)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/Users/troy/Projects/field-tracker-admin-console/functions/node_modules/sharp/lib/constructor.js:10:1)


Error: Functions codebase could not be analyzed successfully. It may have a syntax or runtime error

解决步骤 #

• 安装并激活Node 20.3.0

  1. 执行asdf install nodejs 20.3.0安装指定版本
  2. 在项目根目录运行asdf local nodejs 20.3.0，将该版本设为项目本地默认
  3. 执行node -v验证，确认输出为v20.3.0

• 更新package.json版本约束
  修改engines字段为"engines": { "node": "^20.3.0" }，明确指定符合sharp要求的版本，避免部署流程选用低版本Node

• 重建依赖

  1. 删除functions目录下的node_modules文件夹和package-lock.json文件
  2. 执行npm install，基于Node 20.3.0重新安装所有依赖，确保sharp适配当前Node版本

• 重新部署
  运行firebase deploy --only functions，此时会使用本地激活的Node 20.3.0构建代码，满足sharp的版本要求

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