Express.js+TypeScript会话认证：TS2339属性不存在错误排查

问题描述 #

使用Express.js + TypeScript实现基于会话的认证系统时，编辑器无报错，但控制台编译出现以下TypeScript错误：

TSError: ⨯ Unable to compile TypeScript:
src/controllers/users/authController.ts:21:17 - error TS2339: 属性“loggedIn”在类型“Session & Partial<SessionData>”上不存在。

21     req.session.loggedIn = true;
                   ~~~~~~~~
src/controllers/users/authController.ts:22:17 - error TS2339: 属性“user”在类型“Session & Partial<SessionData>”上不存在。

22     req.session.user = user;
                   ~~~~

    at createTSError (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:587:12)
    at reportTSError (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:591:19)
    at getOutput (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:921:36)
    at Object.compile (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:1189:32)
    at Module.m._compile (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:1295:42)
    at Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
    at Object.require.extensions.<computed> [as .ts] (/Users/apensia/dev/letha-api/node_modules/.pnpm/ts-node@10.0.0_@types+node@20.14.11_typescript@5.5.3/node_modules/ts-node/src/index.ts:1298:12)
    at Module.load (node:internal/modules/cjs/loader:1207:32)
    at Function.Module._load (node:internal/modules/cjs/loader:1023:12)
    at Module.require (node:internal/modules/cjs/loader:1235:19)

项目依赖 #

{
  "devDependencies": {
    "@types/connect-mongo": "^3.1.3",
    "@types/express": "^4.17.21",
    "@types/express-session": "^1.18.0",
    "mongoose": "^8.5.1",
    "nodemon": "^3.1.4",
    "ts-node": "10.0.0",
    "typescript": "^5.5.3"
  },
  "dependencies": {       
    "connect-mongo": "^5.1.0",
    "express": "^4.19.2",
    "express-session": "^1.18.0",
    "mongodb": "^6.8.0"
  }
}

自定义类型扩展尝试 #

为扩展express-session的SessionData接口，添加了自定义类型文件：

// src/@types/libs/express-session/index.d.ts
import "express-session";

declare module "express-session" {
  export interface SessionData {
    user: { [key: string]: any };
    loggedIn: boolean;
  }
}

服务器初始化代码 #

// 主Express.js服务器初始化文件
import "dotenv/config";
import connectDB from "./db";
import express, { Application } from "express";
import morgan from "morgan";
import helmet from "helmet";
import session from "express-session";
import MongoStore from "connect-mongo";
import { specs, swaggerUi } from "./swagger.config";
import { userRouter, reviewRouter, authRouter } from "./routers";

const app: Application = express();
const PORT = process.env.NODE_ENV === "development" ? process.env.PORT : 4001;

// DB Connection
connectDB();

// Misc
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Session
const SESSION_SECRET_KEY = process.env.SESSION_SECRET_KEY as string;
app.use(
  session({
    resave: false,
    secret: SESSION_SECRET_KEY,
    saveUninitialized: false,
    cookie: { secure: true, maxAge: 60 * 5 },
    store: MongoStore.create({}),
  })
);

解决方案建议 #

1. 检查TypeScript配置（tsconfig.json） #

确保自定义类型文件被TypeScript正确识别，需配置typeRoots和include字段：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/@types"],
    "include": ["src/**/*"]
  }
}

• typeRoots：指定TypeScript查找类型定义的目录，必须包含自定义类型所在的src/@types
• include：确保覆盖所有src目录下的文件，包括自定义类型文件

2. 调整自定义类型文件路径 #

将类型文件路径改为src/@types/express-session/index.d.ts，避免嵌套过深导致TypeScript无法自动识别模块声明。

3. 清除ts-node缓存并重启服务 #

ts-node会缓存类型定义，执行以下操作：

• 停止当前服务
• 删除缓存目录（如node_modules/.cache/ts-node）
• 重新启动服务

4. 验证模块合并正确性 #

确保模块声明语法正确：

• 必须先导入express-session
• 扩展的是SessionData接口，而非Session接口
• 接口字段类型定义准确（如user可以定义为更具体的类型，而非{ [key: string]: any }）

5. 临时类型断言（应急方案） #

若需快速验证功能，可临时使用类型断言绕过类型检查，但不推荐长期使用：

(req.session as typeof req.session & { loggedIn: boolean; user: { [key: string]: any } }).loggedIn = true;
(req.session as typeof req.session & { loggedIn: boolean; user: { [key: string]: any } }).user = user;

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