本地构建正常的NextJS项目部署Vercel失败原因排查

DevOps 小满

2026-6-23

问题分析与解决方向

核心症状总结

本地构建、启动完全正常
Vercel构建日志显示成功，但线上页面异常：
- 部分Sass样式失效
- 路由跳转无响应
- 任意路径均指向同一错误页面
- 浏览器控制台提示**缺失"<"**的语法错误

控制台的"<"缺失错误，大概率是请求样式、脚本等资源时返回了HTML（比如404页面），解析HTML开头的"<"时被当成了JS/CSS内容导致语法错误。

检查next.config.mjs中的assetPrefix或basePath配置：如果本地没设置但Vercel上需要（比如自定义域名、子路径部署），会导致资源路径错误。比如部署在https://xxx.vercel.app/my-app但basePath没设为/my-app，资源会请求到根路径，返回404 HTML。
- 解决：确认Vercel项目的部署路径，在next.config.mjs中正确设置basePath，或者移除不必要的assetPrefix。
检查Sass导入路径：本地相对路径可能在构建时被解析错误，比如用了@import '~/styles/xxx'但没配置paths别名，Vercel构建时无法正确解析，导致样式文件缺失。
- 解决：在tsconfig.json或jsconfig.json中配置compilerOptions.paths，确保别名能被正确解析，同时统一使用相对路径或别名导入Sass文件。

如果项目混用App Router（app目录）和Pages Router（pages目录），或者vercel.json的路由规则配置错误，会导致所有路径 fallback到错误页：

检查vercel.json中的routes配置：如果存在错误的重写规则，比如把所有请求都重定向到某个错误页面，就会出现任意路径都指向同一错误页的情况。比如：
```
{
  "routes": [
    { "src": "/(.*)", "dest": "/error" }
  ]
}
```
- 解决：移除错误的重写规则，或者调整规则优先级，确保正常路由能被正确匹配。
检查错误页组件配置：App Router的not-found.tsx或Pages Router的_error.tsx是否被错误配置为全局匹配，比如在app目录下错误放置了覆盖全局的路由组件，或者组件逻辑有问题导致无论什么请求都触发错误页。

虽然构建日志显示成功，但Prisma的生成或部署配置错误可能间接导致页面渲染异常：

检查Vercel构建时是否执行了prisma generate：在package.json的scripts中确认build命令包含该操作，比如：
```
"scripts": {
  "build": "prisma generate && next build"
}
```
如果没执行这个命令，会导致Prisma客户端缺失，页面渲染时抛出错误，进而 fallback到错误页。
检查Prisma环境变量：Vercel上的数据库连接字符串是否正确配置，本地与Vercel的环境变量是否一致。如果数据库连接失败，页面渲染时会报错，导致错误页展示。

本地与Vercel使用的NextJS版本不一致：比如本地用了较新版本，Vercel构建时用了旧版本，导致构建产物不兼容。
- 解决：在package.json中锁定NextJS版本，确保本地和Vercel使用相同版本；同时在Vercel项目设置中关闭包管理器自动检测，强制使用项目指定的包管理器。
Vercel构建缓存复用了旧的错误产物：
- 解决：在Vercel项目的构建页面，点击"Redeploy"并选择"Clear build cache"，重新构建项目。

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