Next.js站点URL末尾追加/?后首页hero图像区块无法渲染求助

核心原因 #

Pages路由模式下，URL末尾携带空查询参数/?时，会触发两类异常：

1. 相对路径引用的静态资源解析基准路径变化，导致hero图片404
2. 路由查询参数判断逻辑异常，空查询参数会让router.query返回空对象而非undefined，容易命中不渲染hero区块的分支

修复步骤 #

1. 修正hero图片资源引用路径 #

打开pages/index.js调整图像引用逻辑：

• 若使用next/image组件：将图片存放在项目public目录下，src统一用根路径写法，示例：

  // 错误写法（相对路径）
  <Image src="./assets/hero-bg.png" alt="hero" fill />
  // 正确写法（根路径，对应public/hero-bg.png）
  <Image src="/hero-bg.png" alt="hero" fill />
  

• 若使用CSS背景图：同样将背景图路径改为根路径：

  /* 错误写法 */
  .hero { background-image: url('./assets/hero-bg.png'); }
  /* 正确写法 */
  .hero { background-image: url('/hero-bg.png'); }
  

2. 修正路由参数判断逻辑 #

检查pages/index.js中用到useRouter的代码，如果存在判断router.query是否为空来控制hero区块渲染的逻辑，调整判断条件，排除空查询参数的影响：

import { useRouter } from 'next/router'

export default function Home() {
  const router = useRouter()
  // 错误判断：/?访问时router.query是空对象，会命中!router.query返回true，导致hero不渲染
  // const showHero = !router.query
  // 正确判断：仅当路由有有效非空查询参数时才隐藏hero
  const hasValidQuery = Object.keys(router.query).length > 0
  const showHero = !hasValidQuery

  return <>{showHero && <Hero />}</>
}

3. 配置全局重定向彻底解决后缀问题 #

在next.config.js中添加重定向规则，将所有携带空查询参数的请求永久重定向到无后缀的正常路径，从访问入口避免异常触发：

/** @type {import('next').NextConfig} */
const nextConfig = {
  async redirects() {
    return [
      {
        source: '/',
        has: [{ type: 'query', key: '', value: '' }],
        destination: '/',
        permanent: true,
      },
      // 如需适配所有路径的空查询参数问题，添加下面这条规则
      {
        source: '/:path*',
        has: [{ type: 'query', key: '', value: '' }],
        destination: '/:path*',
        permanent: true,
      }
    ]
  },
}

module.exports = nextConfig

验证方式 #

本地启动服务后，分别访问根路径和带/?后缀的路径，确认hero区块都能正常渲染，浏览器控制台无资源404报错即可。

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