Next.js项目在Vercel部署失败无报错及构建日志如何排查解决

问题原因 #

• GitHub和Vercel的授权异常：OAuth授权过期、被撤销或者权限配置不足，会导致Vercel无法正常拉取仓库代码、回传构建状态，最终出现无日志、GitHub详情跳转404的情况。
• 项目路径配置错误：如果Next.js项目存放在仓库的子目录中，但你没有在Vercel项目设置中指定对应的根目录，构建流程找不到项目文件会直接静默失败。
• Node.js版本不兼容：Next.js不同版本对Node.js版本有明确要求，比如Next.js 13.4+要求Node.js 16.8及以上版本，如果Vercel构建环境的Node.js版本不符合要求，可能出现无报错的构建中断。
• 构建配置不匹配：Vercel中填写的构建命令、包管理器配置和项目实际配置不符，比如用了pnpm但没有开启Vercel的pnpm支持、package.json中没有对应构建脚本，都会导致构建直接失败无日志。
• Vercel平台临时故障：极少情况是Vercel侧的服务异常，导致构建日志无法正常生成和展示。

修复方案 #

• 重新绑定GitHub授权：进入Vercel个人设置的「关联账号」页面，解绑GitHub账号后重新绑定，勾选需要部署的仓库权限，确保授权完整。
• 修正项目根目录配置：进入Vercel对应项目的「设置」-「通用」页面，找到「根目录」选项，如果Next.js项目在子文件夹中，填写对应相对路径，比如./client，项目在根目录则保持默认即可。
• 统一构建Node.js版本，有两种实现方式：
  • 在项目根目录新建.nvmrc文件，写入本地可正常构建的Node.js版本号，比如18.17.1
  • 在Vercel项目设置的「环境变量」中新增变量NODE_VERSION，值填写对应的版本号
• 核对构建配置：进入Vercel项目的「构建与开发设置」页面，确认配置和项目匹配：
  • 构建命令默认填写next build，也可以根据你用的包管理器改成npm run build/pnpm build/yarn build
  • 输出目录默认是.next，不需要修改
  • 如果使用pnpm作为包管理器，需要在环境变量中新增ENABLE_PNPM = 1
• 本地预构建排查问题：在本地项目根目录运行对应构建命令，比如npm run build，先修复本地构建出现的所有报错，再重新推送代码触发部署。
• 重新创建部署项目：如果以上方法都无效，可以删除Vercel中当前的失败项目，重新关联GitHub仓库新建项目部署，大部分授权类问题都会被自动修复。

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