# @eslint-zod/utils 中文文档

规范地址：https://npmcn.com/package/%40eslint-zod/utils/

版本：6\.4\.0
npm 元数据更新时间：2026-10-23T18:54:12.868Z
中文译文更新时间：2026-11-13T22:22:10.172Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eslint-zod/utils
原文对照：https://npmcn.com/package/%40eslint-zod/utils/?lang=original
项目主页：https://github.com/marcalexiei/eslint-zod#readme
源码仓库：https://github.com/marcalexiei/eslint-zod

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：204 kB，124 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19 \|\| ^22\.12 \|\| \>=24
- 运行依赖：2 个
- 首次发布：2026-05-07T09:35:11.445Z
- 最新版本发布：2026-10-23T18:54:12.322Z
- 近 30 天下载量：800506（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

共享的 Eslint- zod 插件公用事业

## 安装

```sh
npm install @eslint-zod/utils
```

也可以使用：`pnpm add @eslint-zod/utils`、`yarn add @eslint-zod/utils`、`bun add @eslint-zod/utils`

## README

# @slint-zod/图利

[![CI Status](https://img.shields.io/github/actions/workflow/status/marcalexiei/eslint-zod/ci.yml?style=for-the-badge&logo=github&event=push&label=CI)](https://github.com/marcalexiei/eslint-zod/actions/workflows/CI.yml/badge.svg) [![Code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge&logo=prettier)](https://prettier.io/) [![Lint: eslint](https://img.shields.io/badge/lint-eslint-3A33D1?logo=eslint&style=for-the-badge)](https://eslint.org/) [![Open on npmx](https://img.shields.io/npm/v/@eslint-zod/utils.svg?style=for-the-badge&logo=npm)](https://npmx.dev/package/@eslint-zod/utils) [![Open issue tracker](https://img.shields.io/github/issues/marcalexiei/eslint-zod.svg?style=for-the-badge)](https://github.com/marcalexiei/eslint-zod/issues)

共享AST公用事业

-   `eslint-plugin-zod`
-   `eslint-plugin-zod-mini`
-   `eslint-plugin-zod-core`

> \[注\] 此软件包是以前列出的所有软件包的依赖性,所以不需要直接安装.

## API 密码

每个导出都带有用法注释的JSDoc——参考链接的源文件(或您编辑中徘徊)来进行完整描述并举出例子. 此 README 只列出可用的内容 .

### 根出口 - `@eslint-zod/utils`

AST 解析,导入跟踪, transversal, 和固定器助手.

**规则的撰写**

-   `createRuleCreator(getRuleURL)` ——建设规则工厂;每个规则都获得其文件URL,以及 `create` 接收用户选项合并 `defaultOptions`类型 `RuleCreator` (工厂)和 `RuleDefinition` 他们被写作反对的种类 [`@eslint-zod/utils/rule-types`](https://npmcn.com/package/%40eslint-zod/utils/#readme-rule-types--eslint-zodutilsrule-types)
-   `createPluginMeta(packageJSONURL)` — 一个插件 `name`, (中文(简体) ), `version`, (中文(简体) ), `getRuleURL` 财务报告和审定财务报表 `createRule`,从中读取 `package.json`; 规则文件预计在 `docs/rules/<rule-name>.md` 下级 `repository.directory`类型 `PluginMeta`

**导入跟踪范围( S)**

-   `ZodImportScope` 定义插件考虑的导入源的类别; `scope.createTracker({ kind })` 规则如何获得每个文件的导入跟踪器; `kind` 要求,以及 `sourceCode` 使下方的能见度解析器
-   `zodImportScope`, (中文(简体) ), `zodMiniImportScope`, (中文(简体) ), `zodCoreImportScope` - 预建 `ZodImportScope` 实例
-   `scope.createTracker({ kind, sourceCode? })` ——返回的追踪器曝光 `createSchemaVisitor`, (中文(简体) ), `detectZodSchemaRootNode`, (中文(简体) ), `isZodSchemaOfType`, (中文(简体) ), `collectZodChainMethods`, (中文(简体) ), `collectZodSchemaConstraints`, (中文(简体) ), `findZodChainedMethod`,以及导入的帮助. `getZodImportBindings()` 返回所有与它来自的声明相绑定的内容 `resolveZodImport(node)` 编号 : `resolveZodExport(node)` 解开它的 zod 导入的词典范畴的节点, 所以阴影化 `z` 决定: `null` - 用他们过来 `isZodNamespace` 在一条规则中,它的修补者会写出一个导入. `createTracker({ kind })` 选择哪些规格是记录的,哪些是要求的 `'value'` 跳过 `import type { … }` 财务报告和审定财务报表 `{ type … }`, (中文(简体) ), `'type'` 只有这些, `'all'` 两者兼而有之,也是阅读类型位置的规则需要的,因为两种形式都达到一种。 Schema 检测可以达到 **仅限** 通过跟踪器——原始表单需要跟踪器的私人导入地图
-   `tracker.resolveZodSchema(node)` - 那个 `ZodSchemaMeta` 一个表达式评估、跟踪 `const` 绑定 : `const base = z.string()`, (中文(简体) ), `base.optional()` 给 `methods: ['string', 'optional']`。与检测不同,调用不一定是最外向的. `null` 除非每个步骤都是可以证明的图谋——非分解导入,解析结果,帮助者调用或被解结构绑定不是. 需要一个用 `sourceCode`
-   `tracker.createSchemaVisitor({ schemaType?, localSchemas?, onSchema })` - 建设 `{ ImportDeclaration, CallExpression }` 访问者返回一个规则,带有检测和 `schemaType` 过滤器已应用 . **规则的标准形状**; 扩展后添加更多访问者密钥. `localSchemas: true` 还访问根植于本地的链条 `const` 计划( s)`base.isOptional()`),与 `meta` 说明整个计划; `node` 仍然只有本地电话, 所以在选择进入前先检查规则的固定器。 需要一个用 `sourceCode`
-   `tracker.findZodChainedMethod(node, meta, methodName)` ——将一个被链条绑入一个计划(一个名称,或数个中的第一个被链条绑起)的方法定位,用于标出被折断的被链条绑起的呼叫的规则. `null` 表示没有链; 匹配 `member: null` 指被锁在链上,行尸无法命名(`z['number']().finite()`),所以报告没有固定
-   类型 `ZodSchemaImportTracker`, (中文(简体) ), `ZodChainItem`, (中文(简体) ), `ZodChainMember`, (中文(简体) ), `ZodChainedMethodMatch`, (中文(简体) ), `ZodImportBinding`, (中文(简体) ), `ZodImportKind`, (中文(简体) ), `ZodSchemaVisitorOptions`, (中文(简体) ), `ZodTrackerOptions`

**Schema 检测和导航**

-   `findParentSchemaMatchingCondition(node, options)` - 搜索AST,寻找对应的祖先计划
-   `getZodChainedMethodNames(meta)` ——方法被连锁 _打开_ 一个计划,工厂被拆除. `ZodSchemaMeta.methods` 包括命名空间计划工厂(`z.number().safe()` → `['number', 'safe']`),但不针对一个已命名的导入(`number().safe()` → `['safe']`如此一丝不挂 `methods.includes(name)` 匹配异名导入的工厂。 用这个来问"这个"计划链方法X"吗
-   `getZodSchemaBaseType(schemaType)` ——将一个 schema 厂名映射到其基础类型;返回 `ZodSchemaBaseType | null`, (中文(简体) ), `null` 工厂规则不应该有
-   类型 `ZodSchemaMeta` 追踪器是什么 `detectZodSchemaRootNode` 返回(或 `null`(中文(简体) )
-   类型 `ZodSchemaConstraint`, (中文(简体) ), `ZodChainedConstraint`, (中文(简体) ), `ZodCheckArgumentConstraint` ——由追踪器产生的正常化制约 `collectZodSchemaConstraints`

**修补器助手**

-   `buildZodChainRemoveMethodFix(opts)` ——从链中去除一种方法
-   `hasCommentInRange(sourceCode, range)` ——一个注释是否位于一个修饰者将要去掉或重写的范围内
-   `hasParenthesizedReceiver(member)` ——成员表达式的对象是否被括号所包裹(`(z.string()).min(1)`),其中在对象端切入的固定器会留下收尾括号后
-   `buildZodChainReplacementFix(opts)` - 替换一系列方法
-   `buildZodConstraintsRemoveFix(opts)` - 删除一组 `ZodSchemaConstraint`s (链条或检查参数)
-   `buildZodWrapperUnwrapFix(opts)` ——用其论据取代单一论据的收尾电话

**Zod 词汇表**

-   `ZOD_IMMUTABLE_SCHEMA_TYPES` ——已解析出已不可更改的工厂名称
-   `ZOD_MUTATING_CHECK_NAMES` —— Zod 检查更改已验证值的名称
-   `ZOD_NON_SCHEMA_PRODUCING_METHODS` —— Zod 方法名称不返回方案
-   `ZOD_NON_SCHEMA_HELPER_NAMES` 编号 : `isZodNonSchemaHelperCall(meta)` ——上层 `z` (b) 其呼唤产生的是计划以外的产品`z.toJSONSchema`, (中文(简体) ), `z.registry`, (中文(简体) ), `z.parse`); 不同于 `isZodSchemaFactoryCall` 单靠独立支票
-   `ZOD_SCHEMA_FACTORY_NAMES` 编号 : `isZodSchemaFactoryName(name)` ——每个顶级的Zod导出,其调用评价为schema;使用上游而非每个规则的工厂列表
-   `isZodSchemaFactoryCall(meta)` - 是否为 `detectZodSchemaRootNode` 结果构建一个方案;解决 `iso` 编号 : `coerce` 取名空间,并拒绝只使用计数的助手`z.toJSONSchema`, (中文(简体) ), `z.prettifyError`(中文(简体) )
-   `ZOD_STRING_FORMAT_METHODS` - 贬值 `z.string().<format>()` 方法和顶级工厂替换每个; 类型 `ZodStringFormatMethodName`
-   `ZOD_STRING_FORMAT_NAMES` 高级字符串格式的厂名,全部解析为 `string`
-   `ZOD_TYPE_CHANGING_METHODS` ——用链式方法围绕另一种类型重建计划(`array`, (中文(简体) ), `or`, (中文(简体) ), `pipe`; ; 链条较早的检查不会带过; 类型 `ZodTypeChangingMethod`

**检查词汇**

由 API 两种风格共享的冠名, 因此规则逻辑比较 `zod`是因为 `.min(2)` 与 `zod/mini`是因为 `z.minLength(2)` 是一个制约因素.

-   `canonicalizeZodConstraintName(constraint, baseType)` – 将约束的拼写减少至其克名
-   `getZodCheckDescriptor(canonicalName)` - 检查意味着什么:哪一种基础类型接受它,它的范围是什么
-   类型 `ZodCheckDescriptor`, (中文(简体) ), `ZodCheckBound`, (中文(简体) ), `ZodCheckDomain`

### 规则类型 - `@eslint-zod/utils/rule-types`

林特规则API的片段 帮助者阅读。 类型是结构的,所以ESLint和打字-eslint自己的对象可以被指定给他们,而无需安装linter:包唯一的打字-slint依赖是 `@typescript-eslint/types`,为AST.

-   `RuleContext`, (中文(简体) ), `RuleListener`, (中文(简体) ), `RuleModule`, (中文(简体) ), `RuleMeta` - 规则本身
-   `JSONSchema4` 类型 `meta.schema`,从打字机上出售,所以 `RuleTester` 接受规则模块
-   `RuleFix`, (中文(简体) ), `RuleFixer`, (中文(简体) ), `ReportDescriptor`, (中文(简体) ), `ReportFixFunction`, (中文(简体) ), `ReportSuggestionArray`, (中文(简体) ), `SuggestionReportDescriptor` - 报告和修正
-   `SourceCode`, (中文(简体) ), `TokenSearchOptions`, (中文(简体) ), `Scope`, (中文(简体) ), `ScopeVariable`, (中文(简体) ), `ScopeDefinition`, (中文(简体) ), `ScopeReference` 来源和范围

### 共同的规则制定者—— `@eslint-zod/utils/rule-builders/<rule-name>`

每项规则在 `eslint-plugin-zod` 财务报告和审定财务报表 `eslint-plugin-zod-mini` (还有) `eslint-plugin-zod-core`揭露其 `create(...)` 工厂从一个专用的子道。 插件保持规则元数据局部并重用运行时逻辑.

-   `buildConsistentImportCreate(scope)` 出口 `ConsistentImportOptions`;其可选类型参数缩小 `syntax` 选择
-   `buildConsistentImportSourceCreate(scope)` 出口 `ConsistentImportSourceOptions`
-   `buildConsistentObjectSchemaTypeCreate(scope)` 出口 `ConsistentObjectSchemaTypeOptions` 财务报告和审定财务报表 `ZOD_OBJECT_METHODS`
-   `buildConsistentSchemaOutputTypeStyleCreate(scope)` 出口 `ConsistentSchemaOutputTypeStyleOptions` 财务报告和审定财务报表 `ZOD_SCHEMA_TYPE_STYLES`
-   `buildConsistentSchemaVarNameCreate(scope)` 出口 `ConsistentSchemaVarNameOptions`
-   `buildNoAnySchemaCreate(scope)`
-   `buildNoCoerceBooleanCreate(scope)`
-   `buildNoConflictingChecksCreate(scope)` - 还出口 `NoConflictingChecksOptions` 财务报告和审定财务报表 `NoConflictingChecksMessageIds` 合同
-   `buildNoDuplicateSchemaMethodsCreate(scope, excludedMethods)` - 一个 `as const` 列表中命名一个类型更改方法是一个类型错误,因为规则从未到达它; 也导出 `NoDuplicateSchemaMethodsExclusions`
-   `buildNoDynamicSchemaValueCreate(scope)`
-   `buildNoEmptyCustomSchemaCreate(scope)`
-   `buildNoFunctionScopedSchemaCreate(scope)`
-   `buildNoNativeEnumCreate(scope)`
-   `buildNoPromiseSchemaCreate(scope)`
-   `buildNoThrowInRefineCreate(scope)`
-   `buildNoTransformInRecordKeyCreate(scope, transformNames)` —— 说 `transformNames` 与关键化工厂及其限制相匹配,所以一个列表既包括API风格
-   `buildNoUnknownSchemaCreate(scope)`
-   `buildNoUnnecessaryReadonlyCreate(scope)`
-   `buildPreferEnumOverLiteralUnionCreate(scope)`
-   `buildPreferNullishCreate(scope)`
-   `buildPreferTupleOverArrayLengthCreate(scope)`
-   `buildPreferValidateCreate(scope, api)` 仅能说明成功的建议; `api` 是一个 `ZodValidateApiStyle` (单位:千美元)`schema-method` 或者说 `standalone`(中文(简体) )
-   `buildRequireBrandTypeParameterCreate(scope)`
-   `buildRequireErrorMessageCreate(scope)`
-   `buildSchemaErrorPropertyStyleCreate(scope)` 出口 `SchemaErrorPropertyStyleOptions`

这个 `consistent-import` 增购再出口 `IMPORT_SYNTAXES` 财务报告和审定财务报表 `ImportSyntax`:每个语法建设者可以执行. 每个插件都声明它自己规则计划中提供的子集.

### 规则模式—— `@eslint-zod/utils/rule-patterns/<pattern-name>`

规则形状在多个规则中反复出现,以它们不同的名称为参数. 与规则构建者不同的是,这些没有绑在一个规则名上,单个插件可能使用一次.

-   `buildDeprecatedSchemaPropertyCreate(options)` - 在给定的图案上标出已贬值的财产进入 `schemaType` (单位:千美元)`z.number().isInt`出口 `DeprecatedSchemaPropertyOptions`
-   `buildDeprecatedSchemaMethodCreate(options)` 标出一个在计划链中任何地方被贬值的方法(`.isOptional()`出口 `DeprecatedSchemaMethodOptions`
-   `buildCollapseEqualBoundsCreate(options)` ——将等同的下/上绑对倒入同一域的精确形式检查中(`z.string().min(3).max(3)` → `z.string().length(3)`出口 `CollapseEqualBoundsOptions` 财务报告和审定财务报表 `CollapsibleBoundDomain`
-   `buildPreferDedicatedFactoryCreate(options)` - 偏好专门工厂,而不是普通工厂,而倾向于加连锁改造器(`z.looseObject()` 结束 `z.object().passthrough()`出口 `PreferDedicatedFactoryOptions`
-   `buildPreferTopLevelFactoryCreate(options)` - 更喜欢顶级工厂,而不是一般工厂上连锁的腐烂方法(`z.uuid()` 结束 `z.string().uuid()`出口 `PreferTopLevelFactoryOptions` 财务报告和审定财务报表 `TopLevelFactoryReplacement`

## 常见问题

### @eslint-zod/utils 是什么？

共享的 Eslint- zod 插件公用事业

### 如何安装 @eslint-zod/utils？

在项目目录运行 npm install @eslint-zod/utils，或使用 pnpm add / yarn add / bun add。

### @eslint-zod/utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eslint-zod/utils 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eslint-zod/utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19 \|\| ^22\.12 \|\| \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eslint-zod/utils 可以商用吗？

@eslint-zod/utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eslint-zod/utils 的下载量有多少？

根据 npm 官方下载统计，@eslint-zod/utils 在 2026/10/14 – 2026/11/12 这 30 天内被下载 800,506 次，日均约 26,684 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eslint-zod/utils 还在维护吗？

最新版本 6\.4\.0 发布于 2026/10/24（21 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/05/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。