Next.js Intercepting Routes（模态框模式）失效：始终跳转至完整页面

我完全理解你的困扰——按照Next.js官方文档配置了拦截路由，想让/project/[id]以模态框形式在当前页面打开，结果每次都直接跳转到完整页面，模态框根本没出现。结合你提供的代码和目录结构，我帮你梳理下几个关键的排查点和解决办法：

一、先确认触发组件的客户端身份 #

你的ProjectCard.tsx里用了useRouter来触发路由跳转，但App Router中只有客户端组件才能使用useRouter这类客户端API。如果这个组件没有添加'use client'指令，会导致路由逻辑异常，直接触发全页刷新而非拦截路由。

修复方式： #

在ProjectCard.tsx的最顶部添加客户端指令：

'use client';
import { useRouter } from 'next/navigation';
// 其他导入和组件代码...

二、检查ModalLayout的实现是否符合拦截路由的要求 #

拦截路由生效后，Next.js会把@modal插槽的内容渲染到根布局中，但如果你的ModalLayout没有做覆盖式布局的样式，即使渲染了也会和普通页面内容混在一起，看起来像全页跳转。

确保ModalLayout是一个覆盖式组件： #

比如给ModalLayout.tsx添加固定定位、半透明背景等核心样式（示例）：

'use client';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

export default function ModalLayout({ children }: { children: React.ReactNode }) {
  const router = useRouter();

  // 点击背景关闭模态框
  const handleBackgroundClick = () => router.back();

  // 监听路由变化，清理模态框状态
  useEffect(() => {
    const cleanup = () => {
      // 可添加模态框关闭时的动画或状态重置
    };
    router.events.on('routeChangeComplete', cleanup);
    return () => router.events.off('routeChangeComplete', cleanup);
  }, [router]);

  return (
    <div 
      className="fixed inset-0 bg-black/60 flex items-center justify-center z-50 p-4"
      onClick={handleBackgroundClick}
    >
      {/* 模态框内容容器，阻止点击事件冒泡到背景 */}
      <div 
        className="bg-white rounded-lg max-w-3xl w-full max-h-[90vh] overflow-y-auto p-6"
        onClick={(e) => e.stopPropagation()}
      >
        {/* 关闭按钮 */}
        <button 
          onClick={handleBackgroundClick}
          className="mb-4 ml-auto block text-gray-500 hover:text-gray-700"
        >
          ✕ 关闭
        </button>
        {children}
      </div>
    </div>
  );
}

如果你的ModalLayout只是普通的流式布局，就会和主页面内容拼接在一起，看起来和全页跳转没区别。

三、排查路由拦截的核心配置 #

从你的目录结构看，@modal/(.)project/[id]的路径是正确的（(.)表示相对根路由的同级拦截，对应根目录的project/[id]），但还有几个细节要确认：

1. 确认Next.js版本 #

拦截路由是Next.js 13.4+ App Router的特性，如果你用的版本低于13.4，这个功能根本不会生效。可以在项目根目录运行：

npm list next

如果版本过低，升级到最新稳定版：

npm install next@latest

2. 清理开发服务器缓存 #

Next.js的开发服务器有时候会缓存旧的路由配置，导致新的并行/拦截路由不生效：

• 停止开发服务器（Ctrl+C）
• 删除项目根目录的.next文件夹
• 重启npm run dev

3. 检查根布局的modal插槽 #

你的根layout.tsx已经正确接收并渲染了modal参数，这部分没问题，但可以确认下是否有其他嵌套布局覆盖了这个逻辑。

四、快速验证拦截路由是否生效 #

可以在@modal/(.)project/[id]/page.tsx里加一个显眼的调试输出：

'use client';
import { useParams } from 'next/navigation';
import React from 'react';

const ProjectDummy = { /* ...你的数据... */ };

const ProjectModalPage = () => {
  const { id } = useParams() as { id: string };
  console.log(`✅ 模态框页面已渲染，当前项目ID：${id}`); // 新增调试日志
  // ...其他代码...
};

export default ProjectModalPage;

点击项目卡片后打开浏览器控制台，如果能看到这条日志，说明拦截路由已经生效，问题出在ModalLayout的样式或实现上；如果看不到日志，说明路由没被拦截，需要回到前面的步骤重新排查。

按照这些步骤排查下来，应该能解决模态框不出现的问题。如果还有疑问，可以告诉我你的Next.js版本，或者ModalLayout的具体实现代码，我再帮你细化分析~

内容来源于stack exchange