本文详解如何在 fastify 中安全、彻底地禁用 json schema 运行时验证，同时保留 schema 定义以支持 swagger 文档生成，避免破坏 fastify-swagger 或 @fastify/swagger-ui 等插件功能。
本文详解如何在 fastify 中安全、彻底地禁用 json schema 运行时验证，同时保留 schema 定义以支持 swagger 文档生成，避免破坏 fastify-swagger 或 @fastify/swagger-ui 等插件功能。
在 Fastify 应用中，Schema 不仅用于请求/响应校验，更是 OpenAPI 文档（如 Swagger UI）的核心数据源。因此，直接删除 route.schema 或将其设为 null（如通过 onRoute 钩子）虽可绕过验证，但会导致文档生成失败或缺失字段——这正是你遇到 swagger-ui 崩溃的根本原因。
正确的解决路径是：保持 schema 定义完整，仅替换验证逻辑本身。Fastify 提供了高度可定制的 setValidatorCompiler API，它负责将 JSON Schema 编译为实际执行的验证函数。我们只需将其重写为“始终返回 true”的无操作验证器，即可全局跳过校验，又不干扰任何依赖 schema 的下游功能。
✅ 推荐方案：使用 setValidatorCompiler 返回恒真验证器
在 Fastify 实例初始化阶段（例如主应用文件或插件顶层），调用：
fastify.setValidatorCompiler(() => () => true);
该语句含义如下：
- setValidatorCompiler 接收一个工厂函数（返回验证器生成函数）；
- 内层 () => true 是最终被调用的验证函数，它忽略所有输入（包括 data 和 schema），直接返回 true；
- 因此，无论请求体是否符合 schema，Fastify 均视为“校验通过”，且全程不抛错、不中断流程。
? 补充说明：部分示例中出现的 { value } 形式（如 () => (value) => ({ value })）适用于需做数据转换的验证器（如 Ajv 的 coerceTypes），但本场景目标仅为跳过校验，无需转换或包装，故最简、最安全的实现就是 () => () => true。
? 使用位置与注意事项
- 必须在注册任何路由前调用（即早于 fastify.get() / fastify.post() 等），否则已注册路由仍使用默认验证器；
- 若你使用插件封装路由（如你的 module.exports = async (fastify, opts) => { ... }），请确保 setValidatorCompiler 在插件注册前执行，或在插件内部首次访问 fastify 实例时立即设置（推荐在插件顶层同步调用）；
// ✅ 正确：在插件内尽早设置（注意：需在定义路由前）
module.exports = async (fastify, opts) => {
// 关键：此处设置，确保后续所有 route 生效
fastify.setValidatorCompiler(() => () => true);
fastify.get('/stations.json', { schema: opts.schema }, async (req) => {
return { /* ... */ };
});
};- 此方式完全兼容 Swagger 文档生成：因为 opts.schema 依然存在并被 @fastify/swagger 插件读取，所有字段、描述、示例均正常渲染；
- 验证器被跳过，但日志、钩子（preValidation, preHandler）、序列化等其他生命周期环节不受影响；
- 如需按环境动态启用/禁用，可结合配置判断：
if (process.env.NODE_ENV === 'development' || config.validation === false) {
fastify.setValidatorCompiler(() => () => true);
}⚠️ 不推荐的替代方案对比
| 方案 | 是否保留 schema | 是否影响 Swagger | 是否真正跳过验证 | 风险点 |
|---|---|---|---|---|
| onRoute 中清空 route.schema | ❌ 否 | ❌ 崩溃/缺失文档 | ✅ 是 | 破坏文档插件契约，不可维护 |
| schema: null 或 schema: {} | ❌ 否（或语义失效） | ❌ 文档异常 | ✅ 是 | OpenAPI 解析失败，UI 渲染报错 |
| setValidatorCompiler(() => () => ({ value })) | ✅ 是 | ✅ 是 | ⚠️ 否（返回包装对象，可能干扰类型推导） | 非必要转换，增加潜在副作用 |
✅ 总结
禁用 Fastify Schema 验证的黄金法则：不动 schema，只换 validator。fastify.setValidatorCompiler(() => () => true) 是官方支持、零副作用、文档友好的标准解法。它精准满足“关闭校验但保留定义”的核心诉求，是生产环境与开发调试中值得信赖的实践。
