Mongoose静态方法含this时新增方法触发循环引用错误求解

问题场景 #

原本能正常运行的Mongoose Schema，只要添加包含this关键字的静态方法，就会抛出类型错误：

Type of property 'signup' circularly references itself in mapped type...

但如果静态方法完全不使用this，哪怕添加多个都不会报错，比如这个示例是正常的：

// 无this的静态方法（无报错）
userSchema.statics.exampleMethod = function() {
  return 'Hello World';
};

问题原因 #

当静态方法中使用this时，TypeScript的自动类型推导会和Mongoose的类型系统产生循环引用冲突，导致类型检查失败。

解决办法 #

1. 为静态方法显式指定this类型 #

给静态方法的this参数声明明确的Model类型，让TypeScript能正确识别this的指向：

import { Model } from 'mongoose';

// 定义文档类型
interface User {
  email: string;
  password: string;
}

// 扩展Model类型，包含自定义静态方法
interface UserModel extends Model<User> {
  signup(email: string, password: string): Promise<User>;
}

// 为静态方法指定this类型
userSchema.statics.signup = async function(this: UserModel, email: string, password: string) {
  // 安全使用this调用Model的方法
  const existingUser = await this.findOne({ email });
  // ...你的业务逻辑
  return user;
};

2. 显式定义Schema的泛型参数 #

创建Schema时，直接传入文档类型和自定义Model类型作为泛型参数，让Mongoose的类型系统提前明确关联关系：

import { Schema, Model } from 'mongoose';

// 定义文档类型
interface User {
  email: string;
  password: string;
}

// 扩展Model类型，包含自定义静态方法
interface UserModel extends Model<User> {
  signup(email: string, password: string): Promise<User>;
}

// 显式指定Schema的泛型参数<文档类型, Model类型>
const userSchema = new Schema<User, UserModel>({
  email: { type: String, required: true },
  password: { type: String, required: true }
});

// 此时this会自动推导为UserModel类型
userSchema.statics.signup = async function(email: string, password: string) {
  const existingUser = await this.findOne({ email });
  // ...你的业务逻辑
  return user;
};

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