如何在Next.js 14（JavaScript+React）中正确使用Zod？

核心问题定位 #

你碰到的问题本质是Zod的ES模块导出在纯JS环境下，默认导入方式不对，导致拿到的是模块的命名空间对象，而非能直接调用的Zod核心API实例。

正确导入方式 #

直接用这两种导入语法就能解决基础使用问题：

// 方式1：默认导入（优先用这个）
import z from "zod";

// 方式2：解构导入（如果方式1不生效时用）
import { z } from "zod";

另外检查下package.json里有没有"type": "module"——Next.js 14的JS项目默认是ES模块，别改成CommonJS，否则会影响模块导入逻辑。

规范类型提示的JSDoc配置 #

要拿到标准的类型提示，在JS文件顶部加JSDoc标注Zod类型：

// 给z变量直接标注类型
/** @type {import('zod').Zod} */
import z from 'zod';

// 或者按需引入具体类型（可选）
/**
 * @typedef {import('zod').ZodString} ZodString
 * @typedef {import('zod').ZodNumber} ZodNumber
 */

同时调整你的jsconfig.js，删掉纯JS项目不需要的TS相关配置，简化后的配置如下：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"]
    },
    "jsx": "preserve",
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "lib": ["dom", "dom.iterable", "esnext"],
    "target": "es5",
    "moduleResolution": "node",
    "module": "ESNext"
  },
  "include": ["src/**/*", "**/*.js", "**/*.jsx"],
  "exclude": ["node_modules"]
}

验证步骤 #

1. 删除node_modules和.next文件夹，重新执行npm install/yarn install
2. 重启IDE（比如VS Code，需要重启才能加载新配置和类型定义）
3. 在组件里写个简单测试代码验证：

import z from 'zod';

const UserSchema = z.object({
  name: z.string(),
  age: z.number()
});

const user = UserSchema.parse({ name: '张三', age: 25 });
console.log(user);

内容的提问来源于stack exchange，提问作者rashgaroth