PAYATHON 2026

Mongoose 中 timestamps 与 virtual populate 导致 this 类型错误

排障赵师傅

结论

可以同时保留 timestamps: true、SchemaOptions.virtuals 和 SchemaOptions.statics。遇到这类推断冲突时,建议显式声明文档类型、virtual 类型和模型类型,让 Schema、model() 以及静态方法的 this 使用一致的类型。

Mongoose 官方文档也介绍了通过扩展 Model 接口声明静态方法的方案。参考文档

为什么会出现这个错误

从报错看,TypeScript 正在比较两种不同的模型类型:

  • 实际调用方法的模型包含时间戳,但 placeholder 被推断成了 unknown。
  • 静态方法要求的 this 中,placeholder 是 string | null | undefined。

这两种模型类型不兼容,因此即使方法内部没有访问 this,IssueOne.myStaticMethod() 也无法通过 this 上下文检查。

错误提到 castObject(...).placeholder,是因为 TypeScript 比较模型成员时,在 castObject() 的返回类型中发现了差异,不表示代码执行了 castObject()。在 Mongoose 9.2.2 的类型声明中,该方法返回模型的原始文档类型。类型声明

这段报错能说明示例中的类型推断不一致,但还不足以判断具体是哪一方的缺陷,也无法确定哪个版本已经修复。

显式统一类型,保留原来的配置方式

手动声明类型后,三个选项仍然可以放在 schema 构造函数中:

import { Schema, model, type Model } from 'mongoose';

// 数据库中的文档字段
interface IssueOneRaw {
  placeholder?: string | null;
  createdAt: Date;
  updatedAt: Date;
}

// virtual 单独声明,不放进原始文档类型
interface IssueOneVirtuals {
  votes?: unknown[];
}

// 静态方法的调用签名
interface IssueOneStatics {
  myStaticMethod(this: IssueOneModel): void;
}

// 同时包含 Mongoose 模型成员和自定义静态方法
interface IssueOneModel
  extends Model<IssueOneRaw, {}, {}, IssueOneVirtuals>,
    IssueOneStatics {}

const issueOneSchema = new Schema<
  IssueOneRaw,
  IssueOneModel,
  {}, // instance methods
  {}, // query helpers
  IssueOneVirtuals,
  IssueOneStatics
>(
  {
    placeholder: String
  },
  {
    timestamps: true,

    virtuals: {
      votes: {
        options: {
          ref: 'IssueTwo',
          localField: '_id',
          foreignField: 'issueOneId'
        }
      }
    },

    statics: {
      myStaticMethod: function (this: IssueOneModel): void {
        console.log('placeholder');

        // this 是模型,能够访问模型成员
        console.log(this.modelName);
      }
    }
  }
);

const IssueOne = model<IssueOneRaw, IssueOneModel>(
  'IssueOne',
  issueOneSchema
);

IssueOne.myStaticMethod();

这些类型声明需要配套使用:

  1. IssueOneRaw 显式包含时间戳字段。timestamps: true 负责运行时行为,接口负责描述字段类型。默认时间戳字段是 createdAt 和 updatedAt,类型均为 Date。时间戳文档
  2. IssueOneVirtuals 同时传给 Model 的第四个泛型参数和 Schema 的第五个泛型参数。virtual 不属于 MongoDB 中存储的原始字段,应单独声明。virtual 类型文档
  3. schema、模型创建和静态方法的 this 都使用 IssueOneModel,避免各处分别推断出不同的模型类型。泛型参数的位置可对照 Mongoose 9.2.2 的声明。

this: IssueOneModel 是 TypeScript 的特殊参数,只参与类型检查,编译成 JavaScript 后会被移除。调用时仍然写 IssueOne.myStaticMethod(),不需要额外传参。

virtual populate 的类型要另外处理

示例将 votes 声明为 votes?: unknown[],因为问题中没有提供 IssueTwo 的完整结构,无法确定关联文档有哪些字段。

如果项目已经定义了 IssueTwoRaw,且查询返回普通的 hydrated documents,可以改成:

import type { HydratedDocument } from 'mongoose';

interface IssueOneVirtuals {
  votes?: HydratedDocument<IssueTwoRaw>[];
}

IssueTwoRaw 应使用项目中的真实类型。votes 保留可选,用来表示尚未 populate 的情况。声明 virtual populate 不会自动执行关联查询。

ref: 'IssueTwo' 是运行时模型名,仅凭这个字符串无法推断出关联模型的完整 TypeScript 类型。

使用时注意什么

静态方法应使用普通函数或方法简写。需要访问模型的 this 时,不要使用箭头函数,因为箭头函数无法获得 Mongoose 调用时提供的 this。

手动声明文档接口后,需要同步维护接口与 schema。示例中的 createdAt: Date、updatedAt: Date 描述的是正常写入后具有时间戳的文档。对于新建但尚未保存的实例、历史数据,或通过查询投影排除了这些字段的结果,仍需根据实际情况处理字段缺失。

建议启用 strict: true,至少启用 strictNullChecks: true。Mongoose 的自动类型推断依赖这些设置。TypeScript schema 文档

this: any、as any 或 skipLibCheck 无法纠正报错中的 placeholder: unknown,不能代替类型统一。如果业务代码需要调用 this.find()、this.create() 或其他自定义静态方法,完整的模型类型也更便于后续维护。

该方案是否能在 Mongoose 9.2.2 与 TypeScript 5.9.3 下通过编译,仍需实际验证。应用后应使用项目锁定的依赖执行 tsc --noEmit,检查方法调用和查询结果类型。

备注:内容仅供参考。