TypeScript声明文件丢失undefined类型，类型收窄失效求助

安全阿岳

2026-7-20

问题：TypeScript库类型声明丢失null/undefined联合类型，导致类型收窄失效

问题根源

这是TypeScript编译时严格空检查（strictNullChecks）未启用导致的行为：

当strictNullChecks关闭时，TypeScript会将null和undefined视为所有类型的子类型，生成声明文件时会自动从类型谓词中省略null | undefined联合类型
本地直接使用common.ts时，你的项目可能开启了strictNullChecks，所以类型推导正常；但库编译时未开启该选项，导致生成的d.ts丢失了关键类型信息

另外你的tsconfig.json存在重复配置问题：外层的target、module、lib会被compilerOptions内的同名配置覆盖，容易造成编译行为混淆。

解决方案

1. 开启严格模式（推荐）

在compilerOptions中添加"strict": true，它包含strictNullChecks在内的一系列严格类型检查规则，对库开发的类型安全性至关重要。

2. 修复重复配置

将外层的target、module、lib配置移至compilerOptions内，删除冗余的外层配置，确保编译规则统一。

修改后的完整tsconfig.json：

{
  "include": ["src/**/*"],
  "exclude": ["dist", "node_modules"],
  "compilerOptions": {
    "strict": true,
    "declaration": true,
    "esModuleInterop": true,
    "importHelpers": true,
    "jsx": "react-jsx",
    "lib": ["dom", "esnext"],
    "module": "esnext",
    "moduleResolution": "node",
    "outDir": "./dist/esm",
    "resolveJsonModule": true,
    "rootDir": "./src",
    "skipLibCheck": true,
    "sourceMap": true,
    "target": "es6"
  }
}

验证步骤

重新执行编译命令（如tsc）
查看生成的common.d.ts，此时类型谓词会完整保留：

export declare const isNull: (value: any) => value is null | undefined;
export declare const isEmptyArray: (value: unknown[] | null | undefined) => value is null | undefined | [];