Ajv

最快、最流行的 JSON Schema 校验器，广泛支持 Node.js 与浏览器端数据校验，通过代码生成技术实现极致性能。

技术简介说明

Ajv（Another JSON Schema Validator）是 JavaScript 生态中最成熟、使用最广泛的 JSON Schema 校验库，由 Evgeny Poberezkin 于 2015 年创建。其核心创新在于**代码生成（Code Generation）**机制——Ajv 将 JSON Schema 编译为高度优化的 JavaScript 校验函数，直接针对 V8 引擎进行性能调优，使得校验速度远超基于解释执行的同类库。这一设计使得 Ajv 在大规模数据校验场景下具备显著性能优势，特别适合高吞吐量的 API 服务、数据管道和配置系统。

Ajv 支持完整的 JSON Schema 规范演进历程，包括 draft-04、draft-06、draft-07、2019-09 和最新的 2020-12 草案，同时支持 JSON Type Definition（JTD，RFC 8927）。从 v7 开始，Ajv 进行了重大架构重构，统一了内置关键字与用户自定义关键字的处理方式，并将格式校验（如 email、date、uri 等）拆分为独立插件包 ajv-formats，实现了更清晰的职责分离和更灵活的扩展能力。

进入 2025–2026 年，Ajv 已稳定在 v8.x 大版本，npm 年度下载量超过 74 亿次（2025 全年），周下载量约 3.2 亿次，是 npm 生态中下载量最高的包之一。Ajv 被 ESLint、Webpack、Fastify、Express 等大量知名项目作为底层依赖使用，其事实标准地位已不可动摇。

基本信息

• 官网：https://ajv.js.org
• GitHub：https://github.com/ajv-validator/ajv
• License：MIT
• 最新版本：8.20.0（2026-04-24 发布）
• 主要维护者：Evgeny Poberezkin（epoberezkin）
• GitHub Stars：~14,800（2026 年）
• npm 周下载量：~3.2 亿+（2026 年）
• npm 年下载量：~74.5 亿（2025 全年，Kwyzer 数据）
• 首次发布：2015 年
• 语言：TypeScript（v7+ 完全 TypeScript 化）
• 运行环境：浏览器 + Node.js + 边缘函数

快速上手

安装

# npm
npm install ajv
 
# yarn
yarn add ajv
 
# pnpm
pnpm add ajv
 
# 安装格式校验插件（v7+ 需要单独安装）
npm install ajv-formats
 
# 安装扩展关键字插件（可选）
npm install ajv-keywords

提示：从 v7 开始，Ajv 将格式校验拆分为独立的 ajv-formats 包。如果需要校验 email、date、uri 等格式，必须额外安装并注册。

基础配置

import Ajv from 'ajv'
import addFormats from 'ajv-formats'
 
// 创建 Ajv 实例
const ajv = new Ajv({
  allErrors: true,       // 收集所有错误，而非遇到第一个错误就停止
  removeAdditional: true, // 移除不在 Schema 中定义的额外属性
  useDefaults: true,      // 使用 Schema 中定义的默认值
  coerceTypes: true,      // 类型强制转换（如字符串 "123" → 数字 123）
})
 
// 注册格式校验
addFormats(ajv)

最小示例

import Ajv from 'ajv'
import addFormats from 'ajv-formats'
 
const ajv = new Ajv()
addFormats(ajv)
 
// 定义 JSON Schema
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 2 },
    email: { type: 'string', format: 'email' },
    age: { type: 'integer', minimum: 0, maximum: 150 },
  },
  required: ['name', 'email'],
  additionalProperties: false,
}
 
// 编译 Schema 为校验函数（编译一次，反复使用）
const validate = ajv.compile(schema)
 
// 校验数据
const valid = validate({
  name: '张三',
  email: '[email protected]',
  age: 28,
})
 
if (valid) {
  console.log('数据合法！')
} else {
  console.log(validate.errors)
  // [{ keyword: '...', message: '...', params: ..., instancePath: '...' }]
}

核心概念与架构

代码生成机制

Ajv 的核心架构基于运行时编译 + 代码生成。当调用 ajv.compile(schema) 时，Ajv 会：

1. 解析 Schema：遍历 JSON Schema 的所有关键字和约束条件
2. 生成功能代码：将 Schema 翻译为一段等效的 JavaScript 校验函数代码
3. 缓存编译结果：使用 new Function() 或 require() 将生成的代码编译为可执行函数
4. 返回校验函数：后续调用 validate(data) 直接执行已编译的函数，无 Schema 解释开销

这种设计使得重复校验的性能极高——编译成本只需支付一次，后续每次校验都接近原生 JavaScript 的执行速度。

JSON Schema 标准支持

Ajv 完整支持 JSON Schema 规范的多个版本，通过不同的包入口切换：

架构分层

┌─────────────────────────────────────┐
│  ajv-formats / ajv-keywords（插件） │  ← 格式校验、扩展关键字
├─────────────────────────────────────┤
│  Ajv Core（核心引擎）               │  ← Schema 编译、代码生成、校验执行
├─────────────────────────────────────┤
│  fast-deep-equal / uri-js（依赖）    │  ← 底层工具库
└─────────────────────────────────────┘

核心特性

• 代码生成高性能：将 JSON Schema 编译为优化的 JavaScript 函数，校验速度远超解释执行方案，V8 引擎深度优化
• 完整的 JSON Schema 支持：支持 draft-04 到 2020-12 全部主要草案版本，以及 JSON Type Definition（JTD，RFC 8927）
• 插件化扩展：通过 addFormat()、addKeyword() 等 API 支持自定义关键字和格式，生态丰富
• 编译缓存：Schema 编译结果自动缓存，相同 Schema 重复使用时零编译开销
• 异步校验：支持基于 $data 引用的跨字段校验，以及通过自定义异步关键字实现数据库查询等异步校验逻辑
• 数据转换：支持 coerceTypes（类型强制转换）、useDefaults（默认值填充）、removeAdditional（移除多余属性）等实用选项
• 详细错误报告：输出结构化的错误信息，包含 keyword、instancePath、message、params 等字段，便于国际化和本地化展示
• 浏览器兼容：支持在浏览器中运行，提供多种打包格式（ESM、CJS、UMD），可与 Webpack、Rollup、esbuild 等工具配合
• 安全的 $data 引用：允许 Schema 中一个关键字的值引用另一个字段的值，实现跨字段比较（如 maximum: { $data: '1/limit' }）
• TypeScript 友好：v7+ 完全使用 TypeScript 编写，提供完整的类型定义

生态图

核心生态包

社区生态

关键依赖

• fast-deep-equal：高效深度相等比较
• uri-js：URI 解析与校验
• json-schema-traverse：Schema 遍历工具
• require-from-string：从字符串动态加载模块（Node.js 端代码生成用）

知名下游项目

Ajv 作为底层校验引擎被大量知名项目依赖：

• ESLint：规则配置校验
• Webpack / SchemaUtils：配置校验
• Fastify：请求/响应校验
• express-openapi-validator：OpenAPI 规范校验
• Angular CLI：angular.json 配置校验
• Prettier：配置校验
• TS-Node：tsconfig 校验

适用场景

• API 请求/响应校验（结合 Fastify、Express 等框架，校验入参格式、类型、范围）
• JSON 配置文件校验（如 tsconfig.json、angular.json 等工具链配置文件格式验证）
• 数据管道与 ETL（在数据导入、转换流程中对结构化数据进行批量校验）
• 表单数据服务端二次校验（前端提交数据后，后端用 JSON Schema 再次校验，防止绕过前端限制）
• OpenAPI / Swagger 规范校验（校验 API 请求和响应是否符合 OpenAPI 定义）
• 消息队列数据校验（Kafka、RabbitMQ 等消息消费时校验消息格式）
• AI / LLM 输出结构化校验（校验大模型返回的 JSON 是否符合预定义的 Schema 结构）

开发与工程化

Schema 管理最佳实践

src/
├── schemas/
│   ├── user.schema.json       # 用户数据 Schema
│   ├── order.schema.json      # 订单数据 Schema
│   └── common/
│       ├── pagination.json    # 公共分页 Schema
│       └── error-response.json
├── validators/
│   ├── user.validator.ts      # 封装编译后的校验函数
│   └── order.validator.ts

编译与预编译

Ajv 支持两种运行模式：

1. 运行时编译：在应用启动时调用 ajv.compile(schema)，适合开发环境
2. 预编译（推荐生产环境）：使用 ajv 的 standalone 模式，在构建阶段将 Schema 预编译为 JS 文件，运行时无需 new Function() 或 eval()

// build 阶段：预编译 Schema 为独立 JS 文件
import Ajv from 'ajv/dist/standalone'
import fs from 'fs'
 
const ajv = new Ajv({ code: { source: true } })
const validate = ajv.compile(schema)
fs.writeFileSync('validate.js', validate.toString())

CI/CD 集成

• 使用 ajv-cli 在 CI 中校验 Schema 文件的语法正确性
• 在构建流程中加入 Schema 兼容性检查，防止 Schema 变更导致运行时校验失败

性能与安全

性能特点

安全注意事项

• CVE-2025-69873（2026 年 2 月披露）：影响 Ajv v7.0.0-alpha.0 至 v8.18.0，当启用 $data: true 选项时，攻击者可构造恶意 Schema 导致拒绝服务（DoS）。建议升级至 v8.20.0 或更高版本。
• 避免用户输入的 Schema：永远不要直接使用用户提供的 JSON Schema 进行编译，应做白名单限制或沙箱隔离
• 代码生成与 CSP：Ajv 默认使用 new Function() 进行代码生成，在启用了严格 Content Security Policy（CSP）的环境中可能被阻止。解决方案：
  • 使用预编译（standalone）模式
  • 配置 CSP 允许 unsafe-eval（不推荐）
  • 使用 ajv-cli 在构建时预编译所有 Schema
• removeAdditional 的副作用：该选项会直接修改传入的数据对象（mutate），如果数据被其他逻辑引用需注意浅拷贝问题

性能优化建议

• 编译一次、复用多次——避免每次请求都重新调用 compile()
• 生产环境使用 standalone 预编译模式，消除运行时编译开销
• 对于超大 Schema，考虑拆分并用 $ref 引用
• 避免在 Schema 中使用过于复杂的正则表达式，防止 ReDoS

技术对比

何时选 Ajv

• 需要与 JSON Schema 标准严格兼容（如 OpenAPI、Swagger 规范）
• 对校验性能有极致要求（高频 API 服务、大规模数据处理）
• Schema 由外部定义或需要与多语言系统互通（JSON Schema 是跨语言标准）
• 需要在浏览器和 Node.js 中使用同一套 Schema 定义

何时不选 Ajv

• 需要 TypeScript 类型推导（选 Zod）
• 包体积敏感（选 Valibot）
• 需要简洁的链式 API（选 Zod、Yup、Joi）

最佳实践

1. 始终复用编译后的校验函数

// ✅ 正确：编译一次，全局复用
const validateUser = ajv.compile(userSchema)
app.post('/user', (req, res) => {
  if (!validateUser(req.body)) {
    return res.status(400).json(validate.errors)
  }
})
 
// ❌ 错误：每次请求都重新编译
app.post('/user', (req, res) => {
  const validate = ajv.compile(userSchema) // 性能浪费！
  // ...
})

2. 生产环境使用 standalone 预编译

消除运行时 new Function() 调用，同时满足严格的 CSP 策略。

3. 合理配置错误收集

const ajv = new Ajv({
  allErrors: true,  // 生产环境推荐开启，返回所有错误
  verbose: true,    // 开发环境开启，包含更详细的错误信息
})

4. 使用 $ref 组织复杂 Schema

将公共定义（如分页参数、错误格式）抽离为独立 Schema 文件，通过 $ref 引用，保持 Schema 的可维护性。

5. 自定义关键字要谨慎

自定义关键字（addKeyword）功能强大，但要注意：

• 避免与标准 JSON Schema 关键字冲突
• 自定义关键字的校验逻辑要覆盖所有边界情况
• 为自定义关键字编写单元测试

技术局限与边界

• JSON Schema 学习成本：Ajv 基于 JSON Schema 规范，而 JSON Schema 本身是一套复杂的规范体系（多个 draft 版本、数百个关键字），新手需要投入较多学习时间
• TypeScript 类型推导有限：Ajv 无法像 Zod 那样从 Schema 自动推导出 TypeScript 类型，需要借助 json-schema-to-typescript 等第三方工具，且推导结果可能不够精确
• 代码生成与 CSP 冲突：默认的 new Function() 方式在严格 CSP 环境下不可用，必须使用 standalone 预编译模式
• 数据变更（Mutate）：removeAdditional、useDefaults、coerceTypes 等选项会直接修改传入的数据对象，可能导致难以追踪的副作用
• 调试难度：代码生成的校验函数在出错时堆栈信息不够直观，调试体验不如直接执行的业务代码
• 包体积中等：相比 Valibot（~1 KB）和 Zod（~12 KB），Ajv 的打包体积较大（~60 KB），不适合包体积极度敏感的场景
• 不支持链式 API：JSON Schema 是声明式 JSON 对象，无法像 Zod/Joi 那样使用流畅的链式 API

学习资源

• 官方文档：https://ajv.js.org（最权威的参考，含完整 API 和指南）
• Getting Started：https://ajv.js.org/guide/getting-started.html
• JSON Schema 选择指南：https://ajv.js.org/guide/schema-language.html
• GitHub 仓库：https://github.com/ajv-validator/ajv
• JSON Schema 官网：https://json-schema.org（学习 JSON Schema 规范本身）
• DEV 社区教程：https://dev.to/vishdevwork/json-schema-with-ajv-implementation-deep-dive-1cnn
• 掘金中文教程：搜索「Ajv JSON Schema」可找到多篇中文实践文章
• Ajv 中文网：https://ajv.nodejs.cn（非官方中文翻译）
• Stack Overflow：搜索 ajv 标签可找到大量问答
• YouTube 教程：搜索 "Ajv JSON Schema validation" 可找到多个视频教程

2026 年现状

最新版本

• v8.20.0（2026-04-24 发布）：修复了 CVE-2025-69873 安全漏洞（$data 模式 DoS 攻击），并包含多项稳定性改进
• 同时维护 v6.x 分支（v6.15.0，2026-04-23），为尚未迁移的老项目提供安全补丁

发展趋势

• 稳定维护状态：Ajv 已进入成熟维护期，不再有大规模架构变更，主要以安全修复、bug 修复和小幅增强为主
• JSON Schema 2020-12 全面支持：Ajv 是目前对 JSON Schema 2020-12 支持最完整的 JavaScript 实现
• 面临新库竞争：Zod（周下载量 3,100 万+）凭借 TypeScript 原生类型推导能力，在新项目中越来越受欢迎；Valibot 凭借极小包体积在边缘计算场景获得关注
• 不可替代的地位：在需要标准 JSON Schema 兼容的场景（OpenAPI 工具链、配置校验、跨语言 Schema 共享），Ajv 仍然是唯一且不可替代的选择

社区活跃度

• npm 年下载量：2025 年全年约 74.5 亿次，周下载量约 3.2 亿次
• GitHub Stars：约 14,800
• Issue 响应：活跃维护，安全漏洞响应及时（CVE-2025-69873 在披露后快速修复）
• 依赖广度：被 ESLint、Webpack、Fastify、Angular CLI、Prettier 等核心基础设施依赖，生态地位极其稳固

未来展望

• JSON Schema 规范本身仍在持续演进，Ajv 将继续跟进新草案特性
• 随着 OpenAPI 3.1 全面普及（基于 JSON Schema 2020-12），Ajv 在 API 工具链中的角色将进一步强化
• 在 TypeScript-first 的场景中，Zod 等库可能成为首选，但 Ajv 在标准兼容性和性能方面仍保持不可替代的优势