TypeScript 报“Property does not exist”是因为 Mongoose 虚拟属性是运行时挂载的，Schema 不参与类型推导；需手动扩展 Document 类型（如 interface UserDocument extends Document, User { fullName: string; }）并配置 toObject/toJSON 选项启用序列化。
为什么 virtual 声明后 TypeScript 仍报“Property does not exist”？
因为 Mongoose 的 virtual 是运行时挂载的属性，Schema 定义本身不参与 TypeScript 类型推导。即使你用 schema.virtual('fullName') 正确声明，doc.fullName 在 TS 编译期仍被判定为不存在——这是类型系统和运行时行为脱节的典型表现。
核心矛盾在于：Mongoose 的 Document 类型默认只包含 Schema 中显式定义的字段（SchemaTypeOpts），而虚拟属性不在其中。
- 不加干预时，
const user = await User.findById(id)返回的user类型是UserDocument（或泛型Document），不含任何虚拟字段 -
toObject()或toJSON()后的对象也不自动包含虚拟属性，除非显式传{ virtuals: true } - 即使你在 Schema 上调用了
virtual，TS 也不知道该往哪个接口里加这个字段
如何让 Document 类型感知虚拟属性？
必须手动扩展 Document 的类型定义，把虚拟字段“补”进去。最直接的方式是用接口继承 + 泛型覆盖：
interface User {
name: string;
email: string;
}
<p>interface UserDocument extends Document, User {
fullName: string; // ← 手动添加虚拟属性类型
age: number;
}</p><p>const userSchema = new Schema<user model>>({
name: String,
email: String,
});</user></p><p>userSchema.virtual('fullName').get(function () {
return <code>${this.name} (${this.email})</code>;
});</p><p>userSchema.virtual('age').get(function () {
return Math.floor((Date.now() - this.createdAt.getTime()) / (1000 <em> 60 </em> 60 <em> 24 </em> 365));
});
</p>
关键点：
-
Schema构造函数第二个泛型参数Model<userdocument></userdocument>确保find/findOne等方法返回的是带虚拟字段的UserDocument -
UserDocument必须同时 extendsDocument和你的数据接口（User），否则会丢失_id、save等内置成员 - 虚拟属性的 getter 内部使用
this时，其类型是UserDocument，所以能安全访问this.name和this.fullName（递归场景需注意）
虚拟属性在 toObject() 和序列化中为何仍不出现？
即使类型正确，doc.toObject() 默认不会包含虚拟字段——这和类型无关，是 Mongoose 序列化行为控制的。TS 提示没问题，但运行时对象里没有值，容易误以为类型没生效。
必须显式启用：
使用 Scrapfly SDK（scrapfly-sdk）在 TypeScript 或 JavaScript 中进行网页抓取，用于用户请求抓取 URL、绕过反爬虫防护、渲染页面等场景。
- 单次调用：
doc.toObject({ virtuals: true }) - 全局默认（推荐）：在 Schema 上设置
toObject: { virtuals: true }和toJSON: { virtuals: true }
userSchema.set('toObject', { virtuals: true });
userSchema.set('toJSON', { virtuals: true });
否则 Express 的 res.json(doc) 或日志打印 console.log(doc.toObject()) 都看不到 fullName。
嵌套虚拟属性或依赖其他虚拟字段时怎么写类型？
比如 fullName 依赖 firstName 和 lastName 两个虚拟字段，而后者又依赖 name 字段拆分——TS 不会自动推导这种链式依赖关系，必须手动保证类型闭环。
做法是：所有中间虚拟字段都必须在 UserDocument 接口中声明，哪怕只是占位：
interface UserDocument extends Document, User {
firstName: string;
lastName: string;
fullName: string;
}
然后按顺序定义虚拟属性（注意执行顺序）：
userSchema.virtual('firstName').get(function () {
return this.name?.split(' ')[0] || '';
});
<p>userSchema.virtual('lastName').get(function () {
const parts = this.name?.split(' ') || [];
return parts.length > 1 ? parts.slice(1).join(' ') : '';
});</p><p>userSchema.virtual('fullName').get(function () {
return <code>${this.firstName} ${this.lastName}</code>.trim();
});
</p>
如果漏掉 firstName 或 lastName 的类型声明，TS 就会在 fullName 的 getter 里报 Property 'firstName' does not exist on type 'UserDocument'——这不是 Mongoose 问题，是你没告诉 TS 这个字段存在。
复杂虚拟逻辑建议提取为工具函数，并在接口中明确字段名；别指望 TS 自动从字符串拼接里反推字段依赖。
