在 Next.js 14 的 App Router 里，直接使用 await request.json() 看起来省事，但很容易引出 TypeScript 的类型告警：Unsafe assignment of an any value。围绕这个常见问题，本文会说明如何配合 Zod，搭建一套零信任、类型推导完整，同时对 ESLint 也足够友好的请求体验证方案。

在 Next.js 14 App Router 中，直接 await request.json() 会触发 TypeScript 类型警告（Unsafe assignment of an any value）。本文介绍如何结合 Zod，实现零信任、类型推导完备且 ESLint 友好的请求体验证方案。

为什么直接使用 request.json() 会有问题

在 Next.js 14 的 app/api/ 路由里，Request.json() 返回的是 any 类型。这样虽然开发起来更快，但 TypeScript 的类型安全边界也会被直接绕开。

同时，它还会引来 ESLint 的报错，比如 @typescript-eslint/no-unsafe-assignment。这类问题在 API 路由里非常常见。

至于手动做类型断言，像 as RequestBody 这种写法，本质上只是“告诉编译器先别管”。它并不能带来运行时保障。

再看自定义类型守卫，比如 validateRequest。虽然具备一定校验能力，但维护成本偏高，错误提示也不够友好，而且很多时候依然得想办法绕过类型检查。

推荐方案：使用 Zod 进行声明式 + 运行时验证

Zod 是轻量、零依赖、支持类型推导的运行时验证库，完美契合 Next.js API 路由场景。

它不仅能捕获非法输入并返回结构化错误，还能自动从 schema 生成 TypeScript 类型，实现「一次定义、类型与校验共存」。

安装依赖

npm install zod
# 或
yarn add zod

定义请求体 Schema 并自动推导类型

// app/api/route/route.ts
import { z } from 'zod';

const RequestBodySchema = z.object({
name: z.string().min(1, 'Name is required').max(50, 'Name too long'),
});

// 自动推导 TypeScript 类型（无需手动声明 interface）
type RequestBody = z.infer;

在 API 路由中安全解析与验证

import { NextResponse } from 'next/server';
import { z } from 'zod';

const RequestBodySchema = z.object({
name: z.string().min(1, 'Name is required'),
});

export async function POST(request: Request) {
try {
const body = await request.json();

//  安全解析：若验证失败则抛出 ZodError，自动被 catch 捕获
const validated = RequestBodySchema.parse(body);

//  validated 类型为 RequestBody，完全类型安全，无 any 警告
return NextResponse.json({ message: `Hello, ${validated.name}` }, { status: 200 });
} catch (error) {
if (error instanceof z.ZodError) {
//  返回清晰的验证错误（可选：格式化为客户端友好的 error 数组）
return NextResponse.json(
{ error: 'Validation failed', details: error.issues },
{ status: 400 }
);
}
return NextResponse.json(
{ error: 'Bad Request' },
{ status: 400 }
);
}
}

关键优势说明

• 类型安全无警告：RequestBodySchema.parse() 返回精确类型 RequestBody，TypeScript 全程知晓，ESLint 不再报 any 相关错误；
• 运行时强校验：拒绝无效字段、缺失必填项、类型不符等所有非法输入；
• 错误可追溯：ZodError.issues 提供字段级错误定位（如 "name must be a string"），便于调试与前端提示；
• 零重复定义：z.infer 自动生成 TS 类型，避免 interface 与校验逻辑脱节；
• 可扩展性强：支持嵌套对象、数组、联合类型、自定义规则（如邮箱正则、异步校验等）。

注意事项

• 始终在 try/catch 中调用 .parse() —— 验证失败会抛出 ZodError，必须显式处理；
• 若需静默失败（不抛异常），改用 .safeParse()，它返回 { success: boolean; data: T; error: ZodError } 结构；
• 对于大体积请求体，建议配合 request.headers.get('content-length') 做前置大小限制，防止 DoS 攻击；
• 生产环境建议统一错误响应格式（如 { code: string; message: string; details: any }），提升 API 一致性。

通过 Zod 替代手写守卫函数，你不仅消除了类型警告，更构建了一套健壮、可维护、可测试的 API 输入防线——这才是 Next.js 14 类型优先开发的最佳实践。

《夸克》非常好用的免费AI浏览器

下载APP查看