TypeScript 5.7.3对AWS Lambda事件的可选链操作报错排查

环境信息 #

• TypeScript版本：5.7.3
• 依赖类型包：@types/aws-lambda@8.10.147
• TypeScript配置：

{"compilerOptions": {"target": "ES2020","moduleResolution": "nodenext","module": "NodeNext","lib": ["ES2020"],"strict": true,"esModuleInterop": true,"skipLibCheck": true,"skipDefaultLibCheck": true,"rootDir": "./src","baseUrl": ".","outDir": "./dist","strictNullChecks": true,"noImplicitAny": true}}

代码示例 #

用户编写的授权函数代码：

import { APIGatewayRequestAuthorizerEventV2, APIGatewaySimpleAuthorizerWithContextResult } from 'aws-lambda'

type AuthReq = APIGatewayRequestAuthorizerEventV2
type AuthRes = Promise<APIGatewaySimpleAuthorizerWithContextResult<AdminAuthContext>>

export const authorize = async (event: AuthReq): AuthRes => {
  const companyHeader = event?.headers['x-company']
  const authHeader = event?.headers['authorization']
  //....//
}

相关类型定义 #

从@types/aws-lambda中提取的APIGatewayRequestAuthorizerEventV2接口：

export interface APIGatewayRequestAuthorizerEventV2 {
    version: string;
    type: "REQUEST";
    routeArn: string;
    identitySource: string[];
    routeKey: string;
    rawPath: string;
    rawQueryString: string;
    cookies: string[];
    headers?: APIGatewayRequestAuthorizerEventHeaders;
    queryStringParameters?: APIGatewayRequestAuthorizerEventQueryStringParameters;
    requestContext: APIGatewayEventRequestContextV2;
    pathParameters?: APIGatewayRequestAuthorizerEventPathParameters;
    stageVariables?: APIGatewayRequestAuthorizerEventStageVariables;
}

问题描述 #

TypeScript编译时对event?.headers抛出错误：'event.headers' is possibly 'undefined'.ts(18048)，但Esbuild可以正常编译代码，且运行时功能正常。

报错原因 #

1. 类型定义的可选属性约束：从接口定义可见，headers字段带有?标记，属于可选属性，TypeScript会判定该字段可能为undefined。
2. 严格空检查模式开启：你的TS配置中启用了strictNullChecks: true（strict: true已包含该规则），在严格模式下，TypeScript强制要求开发者处理所有可能为null或undefined的变量，规避潜在运行时错误。
3. Esbuild与TypeScript的职责差异：Esbuild仅负责代码转译，不执行类型检查，因此只要语法合法就能完成编译；而TypeScript的核心功能之一是静态类型检查，会严格遵循类型定义的约束提示错误。

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