NextJS使用<Link>组件跳转路由出现404错误，<a>标签可正常访问如何解决？

问题根因 #

你遇到的404现象是Next.js不同版本路由规则不兼容、动态路由配置不当导致的客户端路由匹配失败，原生a标签走服务端请求可以正常命中路由是因为服务端已经配置了对应路径的fallback规则，客户端路由跳转时没有匹配到静态资源就会先触发404缓存。

解决方案 #

场景1：使用Pages Router（Next.js 9.5及以上版本） #

• 先确认pages目录下存在正确的动态路由文件：pages/profile/[id].js/tsx，文件名占位符必须和你代码里的参数名一致，不能写成[username].js等其他名称。
• 废弃旧版as属性写法，改用官方推荐的href对象传参写法，避免路径匹配异常：

<Link 
  className={classes.navbarDesktopMenuButton} 
  href={{
    pathname: "/profile/[id]",
    query: { id: username }
  }}
>
  <Button>
    <strong className={classes.navbarDesktopMenuButton}>My Profile</strong>
  </Button>
</Link>

• 如果是静态导出（执行next export）的部署场景，需要在next.config.js中配置exportPathMap预生成所有动态路由对应的静态页面，否则客户端跳转时找不到预生成的静态资源，就会出现先闪404、后续缓存404后一直访问失败的问题，配置示例：

module.exports = {
  exportPathMap: async function () {
    const paths = {
      '/': { page: '/' },
      // 提前把所有用户profile路径列出来，或者调用接口拉取用户id批量生成
      '/profile/123': { page: '/profile/[id]', query: { id: '123' } },
    }
    return paths
  }
}

场景2：使用Next.js 13+ App Router #

App Router已经完全废弃了as属性，动态路由写法简化为直接传入最终路径：

• 先确认app目录下存在路由文件：app/profile/[id]/page.js/tsx
• 把Link组件直接修改为以下写法即可：

<Link 
  className={classes.navbarDesktopMenuButton} 
  href={`/profile/${username}`}
>
  <Button>
    <strong className={classes.navbarDesktopMenuButton}>My Profile</strong>
  </Button>
</Link>

通用排查点 #

检查你的Button组件内部是否默认渲染了<a>标签，Link组件本身已经会生成<a>标签，嵌套<a>标签属于非法HTML结构，会导致路由行为异常，修改Button组件仅渲染纯按钮元素即可。

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