如何在TypeScript中定义Mongoose Schema的ref字段解决populate类型报错

问题根因 #

你当前给Template类的user字段仅声明了Types.ObjectId类型，TypeScript 不知道该字段在执行 populate 操作后会被替换为User实体，因此访问user.name时会触发类型检查报错。

解决方法 #

方法1：基础联合类型写法 #

直接将user字段的类型声明为ObjectId和User的联合类型，兼容未populate和已populate两种场景：

import { Prop, Schema, SchemaTypes } from '@nestjs/mongoose';
import { Types } from 'mongoose';
// 导入你的User实体类
import { User } from './user.schema';

@Schema({ collection: 'templates' })
export class Template {
    @Prop({
        type: SchemaTypes.ObjectId,
        ref: User.name, // 官方推荐用User.name代替User.id，减少写错的概率
        required: true,
    })
    public user: Types.ObjectId | User; // 联合类型支持两种场景的类型校验

    // 其余字段...
}

查询时如果已经执行了populate，可以直接用类型断言明确类型，就能正常访问User的字段：

// 查询示例
const template = await this.templateModel.findById(templateId).populate('user') as Template & { user: User };
console.log(template.user.name); // 不会触发类型报错

方法2：泛型封装写法（适合高频populate场景） #

如果你的业务场景经常需要对user字段做populate，可以将Template定义为泛型类，更灵活的控制字段类型：

import { Prop, Schema, SchemaTypes } from '@nestjs/mongoose';
import { Types, PopulatedDoc } from 'mongoose';
import { User } from './user.schema';

@Schema({ collection: 'templates' })
export class Template<UserType = Types.ObjectId> {
    @Prop({
        type: SchemaTypes.ObjectId,
        ref: User.name,
        required: true,
    })
    public user: UserType | PopulatedDoc<User>;

    // 其余字段...
}

使用时普通查询直接用Template类型即可，populate后的查询声明为Template<User>类型：

const populatedTemplate: Template<User> = await this.templateModel.findById(templateId).populate('user');
console.log(populatedTemplate.user.name); // 自动识别类型，无需额外断言

小提示：如果使用 Mongoose 7+ 版本，也可以配合内置的HydratedDocument和Populate辅助类型实现更精准的自动类型推断，无需手动声明联合类型也能正常识别populate后的字段类型。

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