Next.js 14 水合错误与客户端组件传参警告问题排查

核心原因拆解 #

1. Link组件水合错误：服务器渲染时，Mongoose文档中的ObjectId会被自动序列化为字符串生成href，但客户端水合时若直接使用未转换的ObjectId对象，会导致客户端生成的href与服务器渲染的HTML不一致，引发UI不匹配。
2. useRouter触发警告：使用useRouter的组件必须添加'use client'指令成为客户端组件，Next.js会严格校验服务端传递给客户端组件的props——Mongoose文档带有toJSON等实例方法，不属于可序列化的普通对象，因此触发警告。而之前用Link时组件是服务端组件，无需序列化传递props，所以不会触发该警告，但水合时的字符串/对象差异会导致UI不匹配。

解决步骤 #

1. 数据库查询时返回普通JS对象（推荐） #

使用Mongoose的.lean()方法查询数据，直接返回无Mongoose额外方法的普通对象，ObjectId会自动转为字符串：

// 查询用户并关联标签，返回普通对象
const users = await User.find().populate('tags').lean();

// 单独查询标签集合
const tags = await Tag.find().lean();

2. 手动转换Mongoose文档为普通对象 #

若无法使用.lean()（需保留Mongoose文档方法），可通过.toObject()手动转换：

const users = await User.find().populate('tags');
// 将文档转为普通对象，getters: true确保ObjectId转为字符串
const plainUsers = users.map(user => user.toObject({ getters: true }));

3. 手动处理props传递（应急方案） #

在服务端组件向客户端组件传递props时，显式将ObjectId转为字符串：

// 服务端组件中传递用户数据给客户端组件
<UserCard 
  user={{
    ...user,
    _id: user._id.toString(),
    tags: user.tags.map(tag => ({ ...tag, _id: tag._id.toString() }))
  }} 
/>

4. 修复Link组件水合问题 #

完成上述数据转换后，重新使用Link组件即可避免水合错误，因为服务器和客户端生成的href都会基于字符串类型的_id：

import Link from 'next/link';

// 用户卡片组件（可作为服务端或客户端组件）
function UserCard({ user }) {
  return (
    <article>
      <Link href={`/users/${user._id}`}>
        <h3>{user.name}</h3>
      </Link>
      <div>
        {user.tags.map(tag => (
          <Link key={tag._id} href={`/tags/${tag._id}`}>
            <span className="badge">{tag.name}</span>
          </Link>
        ))}
      </div>
    </article>
  );
}

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