【报错问题】解决 Vercel 部署报错：Express 类型失效与 TypeScript 2349/2339/2769 错误排查

前言

在将 Node.js 项目（特别是 Express + TypeScript）部署到 Vercel 时，开发者经常会遇到本地运行完美、云端构建失败的情况。本文将针对 pnpm 环境下的常见 TS 编译错误给出解决方案。

常见错误分析与解决

1. Express 无法调用 (Error TS2349)

报错信息： Type 'Express' has no call signatures.

原因： 导入方式不符合 TypeScript 的 ES 模块规范。

解决：
修改导入方式：

typescript 复制代码

import express from 'express'; 
const app = express();

并在 tsconfig.json 中确保开启：

json 复制代码

"esModuleInterop": true,
"allowSyntheticDefaultImports": true

2. Request/Response 属性缺失 (Error TS2339)

报错信息： Property 'headers', 'socket', 'cookie' does not exist on type 'Request/Response'.

原因： TypeScript 编译器未能正确识别 Express 的扩展类型，或者误用了 Node.js 原生的 HTTP 类型。

解决：
手动显式声明类型，并确保安装了 @types/express。

typescript 复制代码

import { Request, Response } from 'express';

export const login = (req: Request, res: Response) => {
    const token = req.headers.authorization;
    res.cookie('token', token); // 现在不会报错了
};

3. JWT 负载类型不匹配 (Error TS2769)

报错信息： Argument of type '{...}' is not assignable to parameter of type 'string'.

原因： jsonwebtoken 的 sign 方法重载匹配失败。
解决：
将 Payload 对象断言为 object 或确定的接口类型：
typescript 复制代码
```
const payload = { sub: user.id, email: user.email };
jwt.sign(payload as object, secret);
```

为什么 Vercel 会报错？

Vercel 构建环境通常比本地更严格。如果你使用了 pnpm，请确保项目根目录有 pnpm-lock.yaml，否则构建服务器可能安装了版本不兼容的依赖。

Content (English Version)

Introduction

When deploying Node.js applications (especially Express + TypeScript) to Vercel, you might encounter build failures even if the project runs perfectly on your local machine. This guide addresses common TS errors in a pnpm environment.

Errors & Solutions

1. Express Not Callable (TS2349)

Issue: Type 'Express' has no call signatures.
Cause: Improper import syntax for ES Modules in TypeScript.
Fix: Use import express from 'express'; and enable esModuleInterop in your tsconfig.json.

2. Missing Properties on Request/Response (TS2339)

Issue: Properties like headers, socket, or cookie are missing.
Cause: The compiler is using the generic Node.js IncomingMessage type instead of the extended Express types.
Fix: Ensure @types/express is in your devDependencies and explicitly type your middleware parameters using Request and Response from the express package.

3. JWT Payload Overload Failure (TS2769)

Issue: jsonwebtoken expects a string but receives an object.
Cause: TS fails to match the correct function overload for the sign method.
Fix: Cast the payload object using as object or a specific interface to satisfy the compiler.

Why does this happen on Vercel?

Vercel performs a clean install and build. Discrepancies between your local node_modules and the production environment (often Linux-based) can trigger these strict type checks. Always ensure your pnpm-lock.yaml is up to date.

Tags: #TypeScript #Vercel #Express #Nodejs #ErrorHandling

复制代码