Next.js 13中React水合错误：<a>标签不匹配问题的解决

问题原因 #

你遇到的Expected server HTML to contain a matching <a> in <a>警告，核心是Next.js 13中Link组件的客户端与服务端DOM渲染逻辑不一致：

• 若使用Pages Router：旧版Link要求内部必须嵌套<a>标签，但你直接将ListItem（styled div）作为Link子元素，导致服务端渲染出<a><div>...</div></a>，客户端React补全标签时出现嵌套冲突。
• 若使用App Router：新版Link会自动将直接子元素转为<a>标签，但styled-components的样式处理干扰了DOM结构，导致两端渲染的HTML不匹配。

解决方案 #

根据你的路由模式选择对应修复方式：

方案1：兼容Pages Router/使用legacyBehavior（推荐） #

给Link添加legacyBehavior属性恢复旧版逻辑，手动嵌套<a>标签包裹ListItem，确保两端DOM结构完全一致：

<Link href="/route1" legacyBehavior>
  <a>
    <ListItem>
      <Icon1 size={70} />
      Item 1
    </ListItem>
  </a>
</Link>

方案2：将ListItem改为styled <a>标签 #

直接把ListItem的基础元素从div改为a，让Link直接绑定跳转逻辑，无需额外嵌套：

// 修改styled组件定义
const ListItem = styled.a`
  /* 保留原有所有样式 */
  text-decoration: none; /* 可选：移除a标签默认下划线 */
`;

// 使用时直接嵌套在Link中
<Link href="/route1">
  <ListItem>
    <Icon1 size={70} />
    Item 1
  </ListItem>
</Link>

方案3：App Router下传递props（若使用App Router） #

如果是App Router，让ListItem接受Link传递的props并内部渲染<a>标签：

// 修改ListItem组件，支持a标签属性
const ListItem = styled.a<React.AnchorHTMLAttributes<HTMLAnchorElement>>`
  /* 保留原有样式 */
  text-decoration: none;
`;

// 使用时传递Link的props
<Link href="/route1" passHref>
  <ListItem>
    <Icon1 size={70} />
    Item 1
  </ListItem>
</Link>

验证修复 #

修改后重启开发服务器，检查控制台是否还有水合错误警告，同时确认页面跳转功能正常。

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