部署Next.js应用至Google App Engine时遇--modules-folder参数错误

错误原因 #

你遇到的Invalid option name ("--modules-folder=/layers/google.nodejs.yarn/yarn_modules/node_modules")错误，核心是Yarn版本不兼容：--modules-folder是Yarn 2+（Berry）的专属参数，但你的项目依赖和engines字段指定的是Yarn 1.x版本，Google App Engine的构建环境默认尝试用Yarn 2的参数调用Yarn 1，引发语法冲突。

解决方案 #

方案1：改用npm管理依赖（最稳妥） #

1. 删除package.json中dependencies里的"yarn": "^1.22.21"
2. 修改engines字段，保留Node版本或指定npm版本：

"engines": {
  "node": ">=16.8",
  "npm": ">=8.x"
}

3. 删除项目根目录的yarn.lock文件，执行npm install生成package-lock.json
4. 更新package.json的gcp-build脚本（之前为空，需指定构建命令）：

"scripts": {
  // ...其他脚本
  "gcp-build": "npm run build",
  // ...
}

5. 重新执行npm run deploy

方案2：强制GAE使用npm构建 #

若不想切换包管理器，可在app.yaml中添加配置，强制GAE用npm而非Yarn：

runtime: nodejs
env: flex
runtime_config:
    operating_system: "ubuntu22"
    nodejs_version: 18  # 指定与项目兼容的Node版本，如18.x
automatic_scaling:
    min_num_instances: 1
    max_num_instances: 10
    cool_down_period_sec: 180
    cpu_utilization:
        target_utilization: 0.9
resources:
    cpu: 2
    memory_gb: 4.6
    disk_size_gb: 10
network:
    name: default
# 添加以下配置强制使用npm
skip_files:
  - yarn.lock
env_variables:
  NODE_ENV: production
build:
  env:
    BUILD_COMMAND: npm run build

同时确保package.json的gcp-build脚本设置为npm run build。

方案3：升级到Yarn 2+（Berry） #

若坚持使用Yarn，可升级到Yarn Berry版本：

1. 本地执行yarn set version berry完成版本升级
2. 项目根目录会生成.yarnrc.yml文件，可按需配置modulesFolder参数
3. 更新package.json的engines字段：

"engines": {
  "node": ">=16.8",
  "yarn": ">=3.x"
}

4. 重新执行部署命令

补充说明 #

Firebase Hosting出现相同错误的原因与GAE一致，采用以上任意方案即可解决。Vercel部署正常是因为其构建环境会自动适配项目指定的包管理器版本，不会出现参数不兼容问题。

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