Vercel CLI 27.1.2部署Next.js报Socket hangup error如何解决

问题场景 #

使用Vercel CLI 27.1.2版本部署Next.js前端项目时触发部署错误，错误现场截图：

根因说明 #

27.1.2是Vercel CLI的历史旧版本，和Next.js 12及以上版本的项目结构识别、构建流逻辑存在已知兼容问题，官方在后续30.x及更高版本中已经全量修复这类部署异常。

修复步骤 #

• 先全局卸载当前安装的旧版Vercel CLI，根据你使用的包管理器执行对应命令：

  # npm用户
  npm uninstall -g vercel
  
  # yarn用户
  yarn global remove vercel
  
  # pnpm用户
  pnpm remove -g vercel
  

• 安装最新稳定版Vercel CLI，禁止指定旧版本号：

  # npm用户
  npm install -g vercel@latest
  
  # yarn用户
  yarn global add vercel@latest
  
  # pnpm用户
  pnpm add -g vercel@latest
  

• 安装完成后执行vercel --version校验版本，确认版本号≥30.0.0即可（当前官方稳定版已迭代至32.x以上，无旧版兼容bug）
• 进入你的Next.js项目根目录，删除本地缓存的.vercel隐藏文件夹：

  # Mac/Linux系统
  rm -rf .vercel
  
  # Windows系统直接在资源管理器打开项目根目录，开启隐藏文件可见后手动删除.vercel文件夹即可
  

• 重新执行部署命令：预览环境部署直接执行vercel，生产环境正式部署执行vercel --prod，按照CLI提示完成账号授权、项目关联即可正常部署。

异常兜底方案 #

如果升级CLI后仍然触发构建错误，按以下规则检查项目配置：

1. 打开项目根目录的package.json，确认scripts下的build命令为Next.js官方默认值"build": "next build"，不要随意修改构建输出路径
2. 不要在vercel.json中手动重写Next.js项目的buildCommand、outputDirectory配置，Vercel会自动识别Next.js项目的构建规则，自定义配置反而会触发构建路径错误
3. 部署前先在本地执行对应包管理器的依赖安装命令（npm install/yarn/pnpm install），补全缺失的依赖包后再重试部署

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