先来看一个常见的开发场景：后端返回的数据里，`status` 字段是数字类型（如 `1`），但在前端展示时，你需要将其转换为“OK”、“Unread”这类可读文案。如果直接在 Zod schema 中为每个字段添加 `.transform()` 来派生新属性，很容易踩坑——Zod 会误认为输入数据中本来就存在这个字段，导致解析时报错，类型推导也会混乱。
其实解决思路非常直观：先定义好基础的对象结构，然后对整个解析结果执行一次整体转换。这样派生字段仅出现在输出侧，不参与输入校验，既简洁又安全。具体实现如下：
import { z } from 'zod';
export enum ReportMessageStatus {
UNKNOWN = 0,
OK = 1,
UNREAD = 2,
DELETED = 3,
}
function transformStatus(status: ReportMessageStatus): string {
switch (status) {
case ReportMessageStatus.OK: return 'OK';
case ReportMessageStatus.UNREAD: return 'Unread';
case ReportMessageStatus.DELETED: return 'Deleted';
default: return 'Unknown';
}
}
// ✅ 正确姿势：基础对象 + 整体 .transform()
export const ReportMessageSchema = z
.object({
id: z.string(),
name: z.string(),
status: z.nativeEnum(ReportMessageStatus),
})
.transform((val) => ({
...val,
statusLabel: transformStatus(val.status), // 派生属性，不会出现在输入中
}));
// 使用示例
const rawData = { id: '203923', name: 'best name', status: 1 };
const parsed = ReportMessageSchema.parse(rawData);
// 类型推导为：{ id: string; name: string; status: ReportMessageStatus; statusLabel: string; }
console.log(parsed.statusLabel); // "OK"
这里有几个关键要点值得记住：
.transform()必须挂载在完整的z.object()实例之后，而不是某个字段上——否则会因为输入中不存在该字段而直接报错，导致 Zod 类型校验失败。- 派生字段（如
statusLabel）仅出现在解析后的输出类型中，输入校验阶段完全不可见，运行时和类型推导始终保持一致，确保类型安全。 - 如果需要反向操作（例如提交表单时排除
statusLabel），可以组合使用.omit({ statusLabel: true })生成一个专门用于提交的 schema，实现输入与输出的分离。 - 对于复杂的转换逻辑，建议单独抽离为函数并添加 JSDoc 注释，这样后续维护会更加清晰高效。
这种方案的优势在于：Zod 的强类型约束完全保留，同时又可以灵活地为前端 UI 层添加各种语义化字段。整体思路简单、可控，且符合直觉，适合在需要派生属性的 TypeScript 项目中推广使用。
