将Cookie逻辑抽离为函数后Express登录接口出现Cookie读取异常

问题描述 #

在Express登录路由中使用JWT做身份认证，为解耦将Cookie相关代码抽离到generateAuthToken函数后出现异常：客户端读取access_token Cookie时提示不存在，报错后Cookie才出现；刷新客户端后可正常读取。对比路由内直接编写与抽离函数的执行时间无显著差异，不想在客户端添加等待逻辑。

原有正常代码 #

const token = jwt.sign(
  { id: userInfo.id, username: userInfo.username },
  process.env.SECRET!,
);
let cookieOptions: CookieOptions = {
  httpOnly: false,
  secure: process.env.NODE_ENV === "production",
};
if (remember) {
  cookieOptions = {
    ...cookieOptions,
    maxAge: 7 * 24 * 3600000,
    expires: new Date(Date.now() + 7 * 24 * 3600000),
  };
}
res.cookie("access_token", token, cookieOptions).json({
  match: match,
  userinfo: {
    id: userInfo.id,
    username: userInfo.username,
    email: userInfo.email,
    firstName: userInfo.first_name,
    lastName: userInfo.last_name,
  },
});

修改后异常代码 #

const { token, cookieOptions } = generateAuthToken(
  {
    id: userInfo.id,
    username: userInfo.username,
  },
  remember,
);
res.cookie("access_token", token, cookieOptions).json({
  match: match,
  userInfo: {
    id: userInfo.id,
    username: userInfo.username,
    email: userInfo.email,
    firstName: userInfo.first_name,
    lastName: userInfo.last_name,
  },
}),

排查方向与解决方案 #

1. 移除多余的尾逗号 #

修改后代码末尾的}),包含多余逗号，会导致响应处理逻辑异常，延迟Cookie发送。将其改为});即可。

2. 校验generateAuthToken的返回值 #

确保该函数返回的cookieOptions与原代码完全一致：

• 确认httpOnly保持false（原代码明确设置）
• secure的判断逻辑必须是process.env.NODE_ENV === "production"
• 当remember为true时，正确合并maxAge和expires属性，不要覆盖原有配置

以下是generateAuthToken的正确实现示例：

function generateAuthToken(userPayload: { id: number; username: string }, remember: boolean) {
  const token = jwt.sign(
    userPayload,
    process.env.SECRET!,
  );
  let cookieOptions: CookieOptions = {
    httpOnly: false,
    secure: process.env.NODE_ENV === "production",
    path: "/" // 显式设置根路径，避免路径匹配问题
  };
  if (remember) {
    cookieOptions = {
      ...cookieOptions,
      maxAge: 7 * 24 * 3600000,
      expires: new Date(Date.now() + 7 * 24 * 3600000),
    };
  }
  return { token, cookieOptions };
}

3. 确认函数同步性 #

如果generateAuthToken是异步函数，必须添加await关键字，否则会拿到undefined的token和cookieOptions，导致Cookie设置失败：

const { token, cookieOptions } = await generateAuthToken(...)

4. 检查Cookie的path属性 #

默认情况下Express的res.cookie会把Cookie的path设为当前路由的路径，如果抽离后的函数意外修改了path，会导致客户端在当前路径下读取不到Cookie。显式设置path: "/"可以确保Cookie在全站生效。

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