Next.js页面间导航时loading.js不显示问题求助

问题排查与修复步骤 #

1. 强制使用客户端导航

loading.js仅在Next.js客户端导航场景下生效，必须用<Link>组件跳转，而非原生<a>标签或页面刷新：

import Link from 'next/link';

// 正确跳转写法
<Link href="/">回到首页</Link>

如果用原生<a>标签，会触发全页刷新，loading.js不会被激活。

2. 单独验证加载组件本身

先确认PageSpinner组件能正常渲染：新建测试页面app/test/page.js，直接引入组件测试：

import PageSpinner from "@/components/page-spinner/PageSpinner";

export default function Test() {
  return <PageSpinner />;
}

如果测试页也看不到动画，说明组件本身有问题：

• 检查组件CSS：是否设置了全屏fixed定位、足够高的z-index（确保覆盖其他内容）
• 检查组件结构：是否有实际的动画元素（如SVG、CSS动画）输出

3. 确认版本兼容性

loading.js是Next.js 13+ App Router的特性，依赖React 18+的Suspense能力，检查package.json版本：

{
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

版本过低请升级到符合要求的稳定版。

4. 模拟慢加载测试

如果数据库查询速度过快，loading.js可能来不及显示，手动添加延迟验证：
修改page.js中的异步逻辑：

export default async function Home() {
  // 模拟2秒加载延迟
  await new Promise(resolve => setTimeout(resolve, 2000));

  const rawProjects =
    await db(`SELECT images.id, project_name, location, image_url, type FROM projects, 
    images WHERE projects.id = images.project_id
    `);

  const projects = groupProjects(rawProjects);

  return <HeroContainer projects={projects} />;
}

用<Link>跳转首页，观察是否能看到加载动画。

5. 检查路由结构与Suspense状态

• 确认loading.js与page.js、layout.js在同一app/(home)/目录下（你的结构是正确的）
• 打开React DevTools，定位到对应路由的Suspense节点：
  • 若状态为resolved：页面已加载完成，loading.js自然隐藏
  • 若状态为pending但看不到动画：问题出在PageSpinner组件的渲染或样式上

额外说明 #

父布局的头部、全局背景图在加载时显示是正常的，loading.js仅替换当前路由段的内容（即children的位置）。如果需要全屏覆盖的加载动画，可在PageSpinner组件中设置：

.page-spinner {
  position: fixed;
  top: 0;
  left: 0;
  width: 100vw;
  height: 100vh;
  background: #fff; /* 或匹配全局背景的颜色 */
  z-index: 9999;
  display: flex;
  align-items: center;
  justify-content: center;
}

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