Next.js项目部署到Github Pages后内部链接失效问题求解

开发者阿泽

2026-10-9

问题根本原因

next/link组件属性传递规则不匹配：Next.js明确要求，如果Link组件包裹的是自定义组件（而非原生<a>标签），必须添加passHref属性才会将href值向下传递给子组件。你的场景中Link包裹了自定义的NavLink组件，未加passHref，导致NavLink接收不到href属性，最终渲染出的a标签自然没有href属性。
next.config.js存在拼写错误：你配置里写的basepatch是无效字段，正确字段名为basePath，Next.js原生的basePath能力未生效，你自行封装的前缀逻辑反而增加了异常概率。
next/link适用场景不匹配：next/link是设计用于Next.js多页面之间的路由跳转的，页内hash锚点跳转不需要使用该组件，强行使用反而会引入不必要的逻辑干扰。
PrefixedLink组件未做路径类型判断：你给所有路径都拼接了pathPrefix，如果是#开头的锚点路径，拼接前缀后会生成/React-Portfolio#about这类非规范的锚点路径，存在兼容性隐患。

规范解决方案

首先修复next.config.js配置，启用Next.js原生前缀处理能力，无需自行封装前缀逻辑：

const isProd = process.env.NODE_ENV === 'production'
module.exports = {
  assetPrefix: isProd ? '/React-Portfolio' : '',
  basePath: isProd ? '/React-Portfolio' : '',
}

开启原生basePath能力后，所有next/link路由、静态资源路径都会自动拼接项目前缀，不需要自己定义环境变量处理。

按场景选择跳转组件：

页内锚点跳转：直接使用原生<a>标签，或者给你的NavLink组件直接传递href属性即可，不需要嵌套next/link，你最后通过该方案解决问题就是因为绕开了next/link的属性传递问题。
跨页面路由跳转：如果要用自定义的NavLink作为Link的子组件，必须添加passHref属性：

<Link href="/projects" passHref>
  <NavLink>我的项目</NavLink>
</Link>

如果你使用的Next.js版本不支持原生basePath，确实需要自行封装前缀处理组件，需要补充锚点判断和passHref配置：

import Link from 'next/link';

const PrefixedLink = ({ href, as = href, children, ...props }) => {
  // 锚点路径不拼接前缀
  const finalAs = href.startsWith('#') ? as : `${process.env.pathPrefix}${as}`
  return (
    <Link
      href={href}
      as={finalAs}
      passHref
      {...props}
    >
      {children}
    </Link>
  )
};

export default PrefixedLink;

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