如何编写Zod验证器使属性推断类型为number|undefined？

问题场景 #

有一个无法修改的接口定义：

interface SomeInterfaceOutOfMyControl {
    someProperty: number | undefined
}

function someFuncOutOfMyControl(obj: SomeInterfaceOutOfMyControl) {}

尝试用Zod编写验证器时，两种写法均出现类型不匹配错误：

• 使用z.optional(z.number())：TypeScript判定属性为可选类型，与接口中「属性必填但值可为undefined」的定义冲突。
• 使用z.union([z.number(), z.undefined()])：解析不含该属性的对象时，TypeScript仍推断属性为可选类型，无法匹配接口要求。

报错信息示例：

error TS2322: Type '{ someProperty?: number | undefined; }' is not assignable to type 'SomeInterfaceOutOfMyControl'.
Property 'someProperty' is optional in type '{ someProperty?: number | undefined; }' but required in type 'SomeInterfaceOutOfMyControl'.

解决方案 #

方案1：强制属性存在，值允许为undefined #

直接用z.union([z.number(), z.undefined()])定义属性规则，Zod会强制要求属性必须存在，值可以是number或undefined，对应的推断类型与目标接口完全匹配：

import { z } from "zod";

const validator = z.object({
    someProperty: z.union([z.number(), z.undefined()]),
});

// 推断类型为 { someProperty: number | undefined }，与接口完全匹配
type ValidatedType = z.infer<typeof validator>;

// 正确用法：输入必须包含someProperty字段，值为number或undefined
const validData = { someProperty: undefined };
const object = validator.parse(validData);
someFuncOutOfMyControl(object); // 无类型错误

方案2：自动补全缺失的属性 #

如果输入数据可能缺少someProperty字段，可添加.default(undefined)，让Zod在运行时自动补全该属性并设置为undefined，同时保持类型推断正确：

const validator = z.object({
    someProperty: z.union([z.number(), z.undefined()]).default(undefined),
});

// 输入无someProperty字段时，Zod会自动添加该属性并设为undefined
const someData = {};
const object = validator.parse(someData);
someFuncOutOfMyControl(object); // 无类型错误

核心区别 #

• z.optional(z.number())：表示属性可选（可不存在），对应类型{ someProperty?: number | undefined }，与接口的必填属性定义冲突。
• z.union([z.number(), z.undefined()])：表示属性必须存在，值为number | undefined，对应类型{ someProperty: number | undefined }，完全匹配目标接口的要求。

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