NestJS应用中如何解决session场景下Cannot set property 'userId' of undefined报错

该报错本质是你尝试赋值的req.session对象本身为undefined，而非userId属性存在问题，核心根源是session中间件未正确挂载到请求链路中。

• 确认session中间件注册顺序：必须在全局前缀、路由注册、其他业务中间件注册之前完成session配置，顺序错误会导致请求进入业务逻辑时session还未挂载。
• 检查session配置合法性：必填参数secret是否正确配置，resave、saveUninitialized两个必填项是否赋值，配置错误会导致中间件静默失效，不会生成session对象。
• 校验HTTP适配器和依赖匹配：如果是使用Fastify替代默认Express作为底层适配器，需确认安装的是Fastify生态的session包，Express和Fastify的session中间件不通用，装错依赖会导致session挂载失败。
• 确认请求对象获取正确：在守卫、拦截器、GraphQL Resolver等场景操作session时，需确认拿到的是原生HTTP请求对象，NestJS封装的上下文对象默认不带session属性，需通过switchToHttp().getRequest()等方法取出原始请求。
• 排查代理层配置：如果前端通过Nginx等反向代理访问后端，需确认代理配置未拦截、丢弃Cookie，session默认基于Cookie实现身份识别，Cookie丢失会导致session初始化失败。

默认Express适配器场景 #

先安装对应依赖：
npm i express-session @types/express-session

在main.ts中按如下顺序配置：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import * as session from 'express-session';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // session中间件必须放在所有其他配置之前
  app.use(session({
    secret: '自定义加密密钥，生产环境需存入环境变量避免硬编码',
    resave: false,
    saveUninitialized: false,
    cookie: {
      maxAge: 24 * 60 * 60 * 1000, // 24小时有效期
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production' // 生产环境开启HTTPS时需设为true
    }
  }));
  // 全局前缀、其他中间件、跨域配置等放在session配置之后
  await app.listen(3000);
}
bootstrap();

配置完成后即可在控制器中通过@Req() req直接操作req.session.userId。

Fastify适配器场景 #

先安装对应依赖：
npm i @fastify/session @fastify/cookie

在main.ts中按如下顺序配置：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import fastifyCookie from '@fastify/cookie';
import fastifySession from '@fastify/session';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter()
  );
  // 先注册cookie依赖，再注册session，顺序不可调换
  await app.register(fastifyCookie);
  await app.register(fastifySession, {
    secret: '自定义加密密钥，生产环境需存入环境变量',
    cookie: {
      maxAge: 24 * 60 * 60 * 1000,
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production'
    }
  });
  await app.listen(3000);
}
bootstrap();

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