如何为Zod的抽象类ZodType扩展自定义方法并兼容TypeScript？

问题背景 #

通过原型给ZodType添加了disabled和isDisabled方法，功能可正常运行，但TypeScript报错提示“属性'disabled'不存在于类型ZodString上”。原因是ZodType是抽象类，普通的接口合并无法扩展其类型定义，导致子类无法识别新增方法。

现有功能正常但类型报错的代码：

z.ZodType.prototype.disabled = function(isDisabled: boolean): ZodType<any, ZodTypeDef, any> {
  this._isDisabled = isDisabled
  return this
}

z.ZodType.prototype.isDisabled = function(): boolean {
  return this._isDisabled
}

// 无效的类型扩展尝试
interface ZodType {
  disabled: (isDisabled: boolean) => void
  isDisabled: () => boolean
  _isDisabled: boolean
}

解决方案：模块扩展（Module Augmentation） #

TypeScript支持通过模块扩展修改现有库的类型定义，针对Zod的场景，需在zod模块范围内扩展对应类型：

1. 扩展Zod的类型声明 #

创建类型声明文件（如zod-extensions.d.ts），或在现有TS文件中添加以下代码：

import { ZodType, ZodTypeDef } from "zod";

declare module "zod" {
  // 扩展Zod的元数据定义，存储自定义状态
  interface ZodTypeDef {
    isDisabled?: boolean;
  }

  // 给ZodType添加自定义方法的类型定义
  interface ZodType<Output = any, Def extends ZodTypeDef = ZodTypeDef, Input = Output> {
    disabled(isDisabled: boolean): this;
    isDisabled(): boolean;
  }
}

2. 优化原型方法实现 #

修改原型方法，将自定义状态存入Zod官方推荐的_def属性（避免污染实例本身），同时用this作为返回类型保证链式调用的类型正确性：

import { z } from "zod";

z.ZodType.prototype.disabled = function(isDisabled: boolean) {
  this._def.isDisabled = isDisabled;
  return this;
};

z.ZodType.prototype.isDisabled = function() {
  return this._def.isDisabled ?? false;
};

3. 验证使用效果 #

此时使用自定义方法，TypeScript会正确识别类型：

const schema = z.object({
  name: z.string().min(3),
  disabledField: z.string().disabled(true)
});

// 正常调用自定义方法
console.log(schema.shape.disabledField.isDisabled()); // 输出true

关键说明 #

• 必须在declare module "zod"块内扩展接口，TypeScript才会将其合并到Zod的原始类型定义中。
• 将自定义状态存入_def是Zod官方推荐的方式，避免与框架内部属性冲突。
• 返回类型用this而非固定的ZodType，保证链式调用时类型不丢失（如z.string().disabled(true).min(3)仍会被识别为ZodString类型）。

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