Next.js 14 Hydration失败求助：Link嵌套NextLink致服务端HTML匹配错误

问题现象 #

自定义Link组件嵌套NextLink后，出现两个核心错误：

• Expected server HTML to contain a matching <a> in <a>
• Hydration错误提示：There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
  应用可正常运行，但错误会影响渲染性能与规范合规性。

问题根源 #

1. 标签非法嵌套：NextLink配合passHref会传递href给子元素，而你的自定义Anchor是styled的<a>，同时MuiLink默认也渲染<a>，多层嵌套导致HTML规范不允许的<a>包<a>结构，直接触发服务端与客户端DOM不匹配。
2. 多余DOM节点干扰：NextLinkComposed外层包裹的<div>属于冗余节点，加剧了Hydration时的结构差异。
3. 服务端与客户端状态不一致：useRouter在服务端渲染时获取的pathname可能与客户端不同，导致active类名在两端渲染不一致，触发Hydration错误。

修复方案 #

1. 重构NextLinkComposed，消除冗余节点与嵌套 #

去掉外层<div>，确保NextLink直接包裹自定义Anchor，仅保留一层<a>标签：

const Anchor = styled('a')({});

export const NextLinkComposed = React.forwardRef<
  HTMLAnchorElement,
  NextLinkComposedProps
>(function NextLinkComposed(props, ref) {
  const {
    to,
    linkAs,
    href,
    replace,
    scroll,
    shallow,
    prefetch,
    locale,
    ...other
  } = props;

  return (
    <NextLink
      href={to}
      prefetch={prefetch}
      as={linkAs}
      replace={replace}
      scroll={scroll}
      shallow={shallow}
      passHref
      locale={locale}
    >
      <Anchor ref={ref} {...other} />
    </NextLink>
  );
});

2. 修正Link组件的状态判断与组件嵌套逻辑 #

改用usePathname（Next.js 13+）获取当前路径，仅在客户端判断active状态，避免服务端与客户端渲染差异；同时确保MuiLink与NextLinkComposed的组合不会产生重复<a>：

import { usePathname } from 'next/navigation'; // Next.js 13+ 适用，旧版本见下方说明

export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
  function Link(props, ref) {
    const {
      as: linkAs,
      className: classNameProps,
      href,
      noLinkStyle,
      role,
      ...other
    } = props;

    const isExternal =
      typeof href === 'string' &&
      (href.indexOf('http') === 0 || href.indexOf('mailto:') === 0);

    // 用usePathname获取当前路径，避免服务端与客户端路径不一致
    const pathname = usePathname();
    const currentPath = typeof href === 'string' ? href : href.pathname;
    
    // 仅在客户端添加active类，消除服务端渲染差异
    const className = clsx(classNameProps, {
      active: typeof window !== 'undefined' && pathname === currentPath,
    });

    if (isExternal) {
      if (noLinkStyle) {
        return (
          <Anchor
            className={className}
            href={href}
            ref={ref}
            target="_blank"
            rel="noopener"
            underline="none"
            {...other}
          />
        );
      }

      return (
        <MuiLink
          className={className}
          href={href}
          ref={ref}
          target="_blank"
          rel="noopener"
          underline="none"
          {...other}
        />
      );
    }

    if (noLinkStyle) {
      return (
        <NextLinkComposed
          className={className}
          ref={ref}
          to={href}
          underline="none"
          {...other}
        />
      );
    }

    // MuiLink的component属性会替换默认<a>，确保最终仅渲染一层<a>
    return (
      <MuiLink
        component={NextLinkComposed}
        linkAs={linkAs}
        className={className}
        ref={ref}
        to={href}
        underline="none"
        {...other}
      />
    );
  },
);

3. Next.js 12及以下版本适配 #

若使用Next.js 12及更低版本，替换usePathname为useRouter，并增加服务端判断：

const router = useRouter();
const pathname = typeof window !== 'undefined' ? router.pathname : '';

额外注意事项 #

• 检查所有使用Link组件的场景，确保没有手动嵌套<a>标签
• 避免在服务端渲染的组件中直接依赖客户端API，所有状态判断需做环境区分

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