TypeScript项目无法导入Zod包：报错原因与修复方案

背景 #

我正在创建一个Hello World TypeScript项目，目录结构如下：

helloWorld.ts文件内容：

var greet: string = "Hello World";
console.log(greet);

执行tsc helloWorld.ts && node helloWorld.js命令可正常运行。

问题 #

在helloWorld.ts顶部添加import { z } from 'zod';后，执行上述命令出现以下编译错误：

node_modules/zod/lib/helpers/util.d.ts:18:47 - error TS2339: Property 'isInteger' does not exist on type 'NumberConstructor'.

18     export const isInteger: NumberConstructor["isInteger"];
                                                 ~~~~~~~~~~~

node_modules/zod/lib/types.d.ts:551:17 - error TS2583: Cannot find name 'Map'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

551     optionsMap: Map<Primitive, ZodDiscriminatedUnionOption<any>>;
                    ~~~

node_modules/zod/lib/types.d.ts:558:23 - error TS2583: Cannot find name 'Map'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

558     get optionsMap(): Map<Primitive, ZodDiscriminatedUnionOption<any>>;
                          ~~~

node_modules/zod/lib/types.d.ts:620:121 - error TS2583: Cannot find name 'Map'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

620 export declare class ZodMap<Key extends ZodTypeAny = ZodTypeAny, Value extends ZodTypeAny = ZodTypeAny> extends ZodType<Map<Key["_output"], Value["_output"]>, ZodMapDef<Key, Value>, Map<Key["_input"], Value["_input"]>> {
                                                                                                                            ~~~

node_modules/zod/lib/types.d.ts:620:183 - error TS2583: Cannot find name 'Map'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

620 export declare class ZodMap<Key extends ZodTypeAny = ZodTypeAny, Value extends ZodTypeAny = ZodTypeAny> extends ZodType<Map<Key["_output"], Value["_output"]>, ZodMapDef<Key, Value>, Map<Key["_input"], Value["_input"]>> {
                                                                                                                                                                                          ~~~

node_modules/zod/lib/types.d.ts:636:84 - error TS2583: Cannot find name 'Set'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

636 export declare class ZodSet<Value extends ZodTypeAny = ZodTypeAny> extends ZodType<Set<Value["_output"]>, ZodSetDef<Value>, Set<Value["_input"]>> {
                                                                                       ~~~

node_modules/zod/lib/types.d.ts:636:125 - error TS2583: Cannot find name 'Set'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

636 export declare class ZodSet<Value extends ZodTypeAny = ZodTypeAny> extends ZodType<Set<Value["_output"]>, ZodSetDef<Value>, Set<Value["_input"]>> {
                                                                                                                                ~~~


Found 7 errors in 2 files.

Errors  Files
     1  node_modules/zod/lib/helpers/util.d.ts:18
     6  node_modules/zod/lib/types.d.ts:551

原因 #

TypeScript默认编译配置的目标版本较低（如ES5），而Zod依赖ES2015及以上版本的内置类型（Map、Set）和API（Number.isInteger），低版本的标准库定义中不包含这些内容，导致编译时无法识别相关类型和属性。

修复方案 #

1. 创建并配置tsconfig.json #

在项目根目录新建tsconfig.json文件，写入以下配置：

{
  "compilerOptions": {
    "target": "ES2015",
    "lib": ["ES2015", "DOM"],
    "module": "CommonJS",
    "strict": true
  },
  "include": ["helloWorld.ts"]
}

• target：设置编译输出的JS版本为ES2015，匹配Zod的语法要求。
• lib：引入ES2015标准库，包含Map、Set等类型和Number.isInteger等API的类型定义。
• module：使用CommonJS模块系统，适配Node.js运行环境。

2. 重新编译运行 #

执行命令tsc && node helloWorld.js即可，TypeScript会自动读取tsconfig.json的配置完成编译。

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