Node.js20环境下Next.js14构建报错及GCP部署500问题求助

核心问题分析 #

构建报错和GCP部署500错误的根源是混合使用npm与yarn导致依赖版本冲突，加上全局Next.js版本与项目本地版本不匹配，缓存残留进一步引发模块找不到的异常。

分步解决步骤 #

• 清理混合包管理器残留

  1. 删除项目根目录下的package-lock.json、yarn.lock文件
  2. 删除node_modules文件夹
  3. 选择单一包管理器重新安装依赖（二选一）：

     # 使用npm
     npm install
     # 或使用yarn
     yarn install
     

• 使用项目本地Next.js执行构建
  不要直接调用全局的next build，改用项目本地版本：

  # 方式1：用npm默认脚本
  npm run build
  # 方式2：用npx调用本地包
  npx next build
  

• 清除构建缓存

  1. 删除项目根目录下的.next文件夹
  2. 带缓存清理参数执行构建：

     npx next build --no-cache
     

• 确认Node.js版本兼容性
  Next.js 13+要求Node.js 18.17+或20.6+，执行node -v检查你的20.x版本是否符合，若版本过低请升级到20系列稳定版。

• GCP部署修复

  1. 本地构建成功后，重新触发GCP部署
  2. 在package.json中指定Node.js版本，确保云端环境与本地一致：

     "engines": {
       "node": "20.x"
     }
     

  3. 部署时清除GCP的构建缓存，避免旧依赖残留

附错误日志 #

C:\Users\Lenovo\OneDrive\Desktop>npx create-next-app@latest radha
√ Would you like to use TypeScript? ... No / Yes
√ Would you like to use ESLint? ... No / Yes
√ Would you like to use Tailwind CSS? ... No / Yes
√ Would you like to use `src/` directory? ... No / Yes
√ Would you like to use App Router? (recommended) ... No / Yes
√ Would you like to customize the default import alias (@/*)? ... No / Yes
√ What import alias would you like configured? ... @/*
Creating a new Next.js app in C:\Users\Lenovo\OneDrive\Desktop\radha.

Using npm.

Initializing project with template: app-tw


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- autoprefixer
- postcss
- tailwindcss
- eslint
- eslint-config-next


added 322 packages, and audited 323 packages in 58s

116 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
Initialized a git repository.

Success! Created radha at C:\Users\Lenovo\OneDrive\Desktop\radha


C:\Users\Lenovo\OneDrive\Desktop>cd radha

C:\Users\Lenovo\OneDrive\Desktop\radha>yarn
yarn install v1.22.19
info No lockfile found.
warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
warning "eslint-config-next > @typescript-eslint/parser > @typescript-eslint/typescript-estree > ts-api-utils@1.0.3" has unmet peer dependency "typescript@>=4.2.0".
[4/4] Building fresh packages...
success Saved lockfile.
Done in 60.13s.

C:\Users\Lenovo\OneDrive\Desktop\radha>next build
- info Creating an optimized production build
- info Compiled successfully
- info Linting and checking validity of types
unhandledRejection Error: Cannot find module 'next/dist/shared/lib/html-context.js'
Require stack:
- C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\pages\_document.js
- C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\server\require.js
- C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\server\load-components.js
- C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\build\utils.js
- C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\build\worker.js
- C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\compiled\jest-worker\processChild.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1048:15)
    at C:\Users\Lenovo\AppData\Roaming\npm\node_modules\next\dist\server\require-hook.js:110:36
    at Module._load (node:internal/modules/cjs/loader:901:27)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:130:18)
    at 8743 (C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\pages\_document.js:39:18)
    at __webpack_require__ (C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\webpack-runtime.js:25:42)
    at 3262 (C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\chunks\262.js:45:22)
    at __webpack_require__ (C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\webpack-runtime.js:25:42)
    at __webpack_exec__ (C:\Users\Lenovo\OneDrive\Desktop\radha\.next\server\pages\_document.js:63:39) {
  type: 'Error',
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    'C:\\Users\\Lenovo\\OneDrive\\Desktop\\radha\\.next\\server\\pages\\_document.js',
    'C:\\Users\\Lenovo\\AppData\\Roaming\\npm\\node_modules\\next\\dist\\server\\require.js',
    'C:\\Users\\Lenovo\\AppData\\Roaming\\npm\\node_modules\\next\\dist\\server\\load-components.js',
    'C:\\Users\\Lenovo\\AppData\\Roaming\\npm\\node_modules\\next\\dist\\build\\utils.js',
    'C:\\Users\\Lenovo\\AppData\\Roaming\\npm\\node_modules\\next\\dist\\build\\worker.js',
    'C:\\Users\\Lenovo\\AppData\\Roaming\\npm\\node_modules\\next\\dist\\compiled\\jest-worker\\processChild.js'
  ]
}
- info Collecting page data .`

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