Next.js混合应用Vercel部署困境：SSR/静态导出与API路由冲突

一、Vercel SSR构建「ENOENT找不到route_client-reference-manifest.js」报错修复 #

这个问题的核心是自定义pageExtensions在Vercel构建环境中未被正确识别，导致客户端引用清单生成异常，可按以下步骤修复：

1. 校验next.config.mjs配置的准确性
   确保构建目标的分支逻辑清晰，且自定义API路由后缀被正确纳入SSR构建范围：

// next.config.mjs
const isStaticExport = process.env.BUILD_TARGET === 'static';

export default {
  pageExtensions: isStaticExport 
    ? ['page.tsx', 'page.ts'] 
    : ['page.tsx', 'page.ts', 'route.api.ts'],
  output: isStaticExport ? 'export' : undefined,
  // 额外添加：确保Vercel能正确识别路由文件
  experimental: {
    clientRouterFilter: true,
  },
};

2. 在Vercel中配置构建环境变量
   进入Vercel项目「Settings → Environment Variables」，添加BUILD_TARGET=ssr，确保Vercel默认构建时触发SSR分支逻辑。

3. 清除Vercel构建缓存
   在Vercel控制台的「Deployments」页面，找到失败的构建记录，点击「Redeploy」并勾选「Clear build cache」，避免旧缓存导致的清单生成异常。

4. 规范API路由目录结构
   确保所有.route.api.ts文件放在app/api/目录下，符合Next.js App Router的路由规范，避免Vercel构建时遗漏路由文件。

二、单一代码库兼容两种构建的最佳实践 #

1. 用脚本区分构建目标 #

在package.json中添加明确的构建脚本，避免手动切换配置：

{
  "scripts": {
    "build:vercel": "BUILD_TARGET=ssr next build",
    "build:capacitor": "BUILD_TARGET=static next build"
  }
}

2. 隔离动态与静态逻辑 #

• 动态API路由（如OAuth回调）统一使用.route.api.ts后缀，仅在SSR构建时生效；
• 静态页面使用.page.tsx/.page.ts后缀，两种构建均包含；
• 用环境变量做条件代码分割，避免静态构建时打包SSR依赖：

// 页面组件中示例
if (process.env.BUILD_TARGET === 'ssr') {
  // SSR专属逻辑：如直接调用后端接口获取数据
} else {
  // 静态导出逻辑：如跳转至Vercel部署的API地址完成OAuth
}

3. 静态导出时的动态逻辑替代方案 #

对于OAuth回调这类无法静态化的逻辑，静态导出的Capacitor应用可直接请求Vercel部署的SSR API：

• 在Capacitor配置中设置API基础地址：

// capacitor.config.ts
export default {
  server: {
    url: process.env.BUILD_TARGET === 'static' ? 'https://your-vercel-domain.com' : undefined,
  },
};

• 在Vercel的API路由中配置CORS，允许Capacitor应用的域名访问。

三、可行架构方案 #

方案1：环境变量驱动的双构建模式（推荐） #

• 核心逻辑：通过BUILD_TARGET环境变量控制next.config.mjs的pageExtensions和output模式，Vercel默认用SSR构建，Capacitor用静态导出；
• 优势：单一代码库，无需拆分代码，配置成本低；
• 注意：确保环境变量在构建时正确传递，Vercel构建环境需开启「Automatically expose System Environment Variables」。

方案2：API路由独立部署+静态应用代理 #

• 核心逻辑：将动态API路由单独部署在Vercel SSR服务上，静态导出的Capacitor应用通过代理或直接调用Vercel API地址处理动态逻辑；
• 实现：在静态构建的next.config.mjs中添加重写规则：

// 静态构建时的重写配置
async rewrites() {
  return [
    {
      source: '/api/:path*',
      destination: 'https://your-vercel-domain.com/api/:path*',
    },
  ];
}

• 优势：静态包完全无动态逻辑，避免构建冲突，API路由独立维护；
• 注意：需处理跨域问题，Vercel API需配置CORS允许Capacitor域名访问。

方案3：Monorepo拆分（可选） #

• 核心逻辑：将前端静态页面和动态API路由拆分为两个独立包，前端包用Next.js静态导出，API包用Next.js SSR部署在Vercel；
• 优势：完全隔离两种构建逻辑，无配置冲突；
• 缺点：增加代码维护复杂度，共享组件需通过内部包管理。

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