Next.js静态构建后客户端导航失效问题排查与解决

原因 #

当开启output: 'export'和trailingSlash: true静态导出时，Next.js会为每个页面生成[page]/index.html的文件结构。但使用Link href="test"这种无尾部斜杠的相对路径时，浏览器会将其解析为/test，静态服务器会自动重定向到/test/以匹配index.html文件，这个重定向过程触发了全页刷新，而非Next.js的客户端路由跳转。该问题属于Next.js静态导出模式下的路由匹配逻辑bug。

修复方案 #

方案1：统一Link路径为带尾部斜杠的格式 #

将所有Link组件的href改为带尾部斜杠的路径，绝对或相对路径均可：

// 绝对路径示例
<Link href="/test/">My test link</Link>

// 相对路径示例
<Link href="./test/">My test link</Link>

这样路径会直接匹配到test/index.html，触发客户端路由跳转，避免全页刷新。

方案2：关闭trailingSlash配置 #

修改next.config.mjs，关闭trailingSlash：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  trailingSlash: false,
};

export default nextConfig;

此时静态导出会生成test.html文件，Link href="test"会直接匹配该文件，正常触发客户端导航。注意这种方式下URL不会带尾部斜杠，需保持所有路由路径格式一致。

验证修复 #

修改完成后，重新执行构建和静态服务启动命令：

npm run build
npx http-serve -c-1 out

点击链接即可验证客户端导航是否正常工作。

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