部署NextJS T3-Stack至Vercel失败：缺失routes-manifest.json文件

问题描述 #

部署T3-Stack项目到Vercel时，构建阶段完成页面生成后报错：

Error: The file "/vercel/path0/dist/routes-manifest.json" couldn't be found. This is normally caused by a misconfiguration in your project.

多次重新部署、删除重建项目均无效，完整构建日志如下：

[04:52:20.975] info  - Collecting page data...
[04:52:25.837] info  - Generating static pages (0/6)
[04:52:25.923] info  - Generating static pages (1/6)
[04:52:25.938] info  - Generating static pages (2/6)
[04:52:25.950] info  - Generating static pages (4/6)
[04:52:25.970] info  - Generating static pages (6/6)
[04:52:25.982] info  - Finalizing page optimization...
[04:52:25.985] 

[04:52:26.004] Route (pages)                              Size     First Load JS
[04:52:26.006] ┌ ○ /                                      3.28 kB         110 kB
[04:52:26.006] ├   /_app                                  0 B             107 kB
[04:52:26.006] ├ ○ /404                                   181 B           107 kB
[04:52:26.006] ├ λ /api/auth/[...nextauth]                0 B             107 kB
[04:52:26.006] ├ λ /api/examples                          0 B             107 kB
[04:52:26.007] ├ λ /api/restricted                        0 B             107 kB
[04:52:26.007] └ λ /api/trpc/[trpc]                       0 B             107 kB
[04:52:26.007] + First Load JS shared by all              109 kB
[04:52:26.007]   ├ chunks/framework-3b5a00d5d7e8d93b.js   45.4 kB
[04:52:26.007]   ├ chunks/main-94d897311acc2837.js        27.1 kB
[04:52:26.007]   ├ chunks/pages/_app-4e49c70b8a55ab64.js  33.2 kB
[04:52:26.007]   ├ chunks/webpack-ee7e63bc15b31913.js     815 B
[04:52:26.007]   └ css/14a4ce6fb40c3e06.css               2.16 kB
[04:52:26.007] 

[04:52:26.008] λ  (Server)  server-side renders at runtime (uses getInitialProps or getServerSideProps)
[04:52:26.008] ○  (Static)  automatically rendered as static HTML (uses no initial props)
[04:52:26.008] 

[04:52:26.389] Error: The file "/vercel/path0/dist/routes-manifest.json" couldn't be found. This is normally caused by a misconfiguration in your project.
[04:52:26.389] Please check the following, and reach out to support if you cannot resolve the problem:
[04:52:26.390]   1. If present, be sure your `build` script in "package.json" calls `next build`.  2. Navigate to your project's settings in the Vercel dashboard, and verify that the "Build Command" is not overridden, or that it calls `next build`.  3. Navigate to your project's settings in the Vercel dashboard, and verify that the "Output Directory" is not overridden. Note that `next export` does **not** require you change this setting, even if you customize the `next export` output directory.
[04:52:26.390] Learn More: https://err.sh/vercel/vercel/now-next-routes-manifest

解决方案 #

1. 确认package.json的build脚本 #

打开项目根目录的package.json，确保scripts里的build命令为：

"scripts": {
  "build": "next build"
}

不要添加next export——T3-Stack依赖tRPC、NextAuth等服务器端功能，静态导出会破坏这些功能，同时生成out目录而非dist，导致Vercel无法识别正确的路由清单。

2. 检查Vercel项目的构建配置 #

进入Vercel项目的Settings → Build & Development Settings：

• 确保Build Command为空（自动使用package.json脚本）或明确设置为next build，不要自定义其他命令
• 确保Output Directory为空——Next.js默认将构建产物放在.next目录，Vercel会自动识别，手动设置dist或out会引发路径错误

3. 移除Next.js配置中的静态导出设置 #

检查next.config.js，如果存在以下配置，直接删除：

module.exports = {
  output: 'export' // 删除该行
}

该配置会强制生成静态导出产物，与T3-Stack的服务器端架构冲突，是触发该错误的常见原因。

4. 强制清理缓存重新部署 #

在Vercel部署页面点击Redeploy，勾选**"Do not use the build cache"**，强制重新构建项目，避免缓存残留的异常产物影响部署。

5. 验证依赖版本兼容性 #

确保Next.js版本与T3-Stack的其他依赖（如tRPC、next-auth）兼容，建议使用T3 CLI初始化时推荐的版本或升级到最新稳定版，版本不兼容可能导致构建产物异常。

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