Next.js 14 Intercepting routes生产环境失效问题求助

摘要 #

Next.js 14的Intercepting routes功能在本地（localhost:3000）正常运行，但部署到生产环境后完全失效。

问题现象 #

• 本地环境：点击页面中的「Image 1」链接，黑色模态框正常弹出，符合预期。
• 生产环境：点击相同链接会直接跳转到新页面，模态框不出现，不符合预期。

项目结构 #

/app
  @modal
    default.tsx
    (.)photos
      [id]
        page.tsx
  default.tsx
  layout.tsx
  page.tsx
  photos
    [id]
      page.tsx

关键代码示例 #

app/layout.tsx #

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
  metadataBase: new URL('https://nextgram.vercel.app'),
};

export default function RootLayout({
  children,
  modal,
}: Readonly<{
  children: React.ReactNode;
  modal: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        {children}
        {modal}
      </body>
    </html>
  );
}

app/page.tsx #

import Link from 'next/link'

export default function Home() {
    return (
        <div>
            <Link href="/photos/1">Image 1</Link>
        </div>
    )
}

app/@modal/(.photos)/[id]/page.tsx #

export default function PhotoModal({
    params: { id: photoId },
}: {
    params: { id: string }
}) {
    return <div className="absolute inset-0 h-full w-full bg-black">MODAL SHOWING</div>
}

app/photos/[id]/page.tsx #

export default function PhotoPage({
    params: { id },
  }: {
    params: { id: string };
  }) {
    return <div className="card">{id}</div>;
  }

app/default.tsx #

export default function Default() {
    return null;
}

问题排查与解决方案 #

1. 修正metadataBase配置
   当前代码中metadataBase指向了Vercel示例项目的域名，需替换为自身生产环境的域名，避免路由解析时出现跨域或路径匹配错误。

2. 检查部署平台的构建模式
   拦截路由依赖Next.js App Router的动态路由能力，若部署时使用了静态导出（next export）会导致功能失效。需确保部署平台使用next build && next start的服务器端渲染模式，而非静态导出。

3. 验证路由匹配规则
   确认@modal路由组下的(.)photos路径前缀正确，(.)表示相对于当前路由层级拦截，需与目标路由/photos/[id]完全匹配。

4. 对齐本地与生产环境的Next.js版本
   确保生产环境安装的Next.js版本与本地开发环境一致，版本差异可能导致功能兼容性问题。

验证步骤 #

1. 修改metadataBase为生产环境域名后重新构建部署
2. 在部署平台配置中切换为Next.js服务器端渲染模式
3. 清除生产环境缓存后重新测试路由跳转

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