如何用 Zod 的 z.config() 全局配置 locales、jitless 与 memoizer【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zodz.config()是 Zod 4 提供的全局配置入口一次调用可以改变整个进程里所有 schema 的行为。本文覆盖三个最常用的配置项locales全局错误信息语言、jitless在 CSP / 禁用 eval 的环境里关闭 AOT 编译、memoizer为 Zod Mini 开启循环引用数据支持。适用环境是已安装zod包zod或zod/mini入口的 Node.js / 浏览器项目。用 z.config() 配置 locales 全局错误语言Zod 4 用localesAPI 全局翻译错误信息。先了解两个默认行为来自 error-customization.mdx常规zod库会自动加载enlocalezod/mini默认不加载任何 locale所有错误信息都是Invalid input。静态配置从 zod/locales 导入import * as z from zod; import { en } from zod/locales; z.config(en());Zod Mini 侧写法相同只是入口换成zod/miniimport * as z from zod/mini; import { en } from zod/locales; z.config(en());静态配置直接用 z.locales所有 locale 都从zod以z.locales导出可以直接调用import * as z from zod; z.config(z.locales.en());Rollup 和 Webpack 会把它 tree-shake 到你实际使用的 locale。esbuild 不行用import { z } from zod或import z from zod时会把全部 locale 打进包在 esbuild 环境请优先import * as z from zod。可选分支懒加载 locale需要按用户语言动态切换时文档给出的做法是动态 importlocale 名如fr、ja、zhCNimport * as z from zod; async function loadLocale(locale: string) { const { default: locale } await import(zod/v4/locales/${locale}.js); z.config(locale()); }; await loadLocale(fr);由于 locale 的error参数是在.parse()时而非构建 schema 时才调用一次定义好的 schema 会在每次 parse 时采用当前语言——切换 locale 后无需重建 schema。验证 locales 是否生效可用的 locale 列表节选完整 60 项见 error-customization.mdx 的 Locales 小节en、fr、ja、ko、ru、zhCN简体中文、zhTW繁体中文等。判断方式以文档给出的默认行为为基准Zod Mini 未配置 locale 时错误信息是Invalid input执行z.config(en())后同样的safeParse失败会输出英文标准信息例如invalid_type、too_short这类 code 对应的完整句子。如果信息仍停留在Invalid input说明z.config没有生效。注意优先级locale error map 在 错误优先级链 中排最低check 级 → schema 级 → per-parse → 全局customError→ locale所以 schema 里写死的错误信息会盖过 locale。用 jitless 在 CSP 环境关闭全局编译Zod 的 AOT 编译z.compile()/import zod/compile底层用new Function生成校验代码在 CSP 或禁用 eval 的环境里不可用。全局模式在这种情况下需要手动降级见 compile.mdxz.config({ jitless: true });配置后的行为边界全局编译模式import zod/compile或node --import zod/compile启动的自动编译遇到jitless: true会「stands down」即不再尝试生成代码schema 保持标准解析器路径。直接调用z.compile()是显式 opt-in不受jitless影响仍会尝试代码生成如果运行环境拒绝new Function该 schema 原样返回未编译与任何一次「拒绝编译」的行为一致。也就是说jitless只保护「全局自动编译」这条路径不会拦截你显式写出的z.compile()调用。如果需要在热路径上确认 schema 确实编译成功文档给出的手段是z.compile(Schema, { strict: true })——编译失败时抛ZodCompileAsyncErrorasync schema或ZodCompileUnsupportedError其余原因而不是静默回退。用 memoizer 为 Zod Mini 支持循环引用数据Zod 递归 schema 处理循环引用输入常规zod开箱即用zod在导入时自动安装 memoizer见 packages/zod/src/v4/classic/schemas.ts。Zod Mini 出于包体积考虑默认不带必须显式注册见 api.mdx 的 Recursive objects 小节 与 zod-4-5 发布说明// Zod Mini requires a memoizer, registered before schemas are defined z.config({ memoizer: z.memoizer() });关键约束memoizer 必须在定义任何 schema 之前注册否则后续定义的递归 schema 不会获得循环支持。文档给出的完整示例与验证方式递归的Category输入自引用// Zod Mini 侧 z.config({ memoizer: z.memoizer() }); const Category z.object({ name: z.string(), get subcategories() { return z.array(Category); }, }); const input: any { name: root, subcategories: [] }; input.subcategories.push(input); const result Category.parse(input); result.subcategories[0] result; // true成功条件就是文档示例中的断言解析结果result.subcategories[0] result为true即输出图镜像输入图的循环结构。常规zod侧同一输入还满足result.subcategories[0].subcategories[0] result。配置顺序与限制小结三项配置都通过z.config()传入互不冲突locale 直接传 locale 对象z.config(en())jitless和memoizer走配置对象z.config({ jitless: true })、z.config({ memoizer: z.memoizer() })。memoizer必须在 schema 定义前注册locales在 parse 时生效随时可以切换。import zod/compile是应用层手段而非库层手段zod/mini入口需要手动补 locale 和 memoizer常规zod入口两者都不需要。各配置项的完整说明见 error-customization.mdxlocales 与错误优先级、compile.mdxjitless与 CSP、api.mdx递归对象与 memoizer。【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zod创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考