深入理解与排查JWT过期时间设置问题

本文旨在探讨Node.js应用中JSON Web Token (JWT) 过期时间设置不生效的常见问题，特别是当使用“7d”和“7h”等字符串形式的持续时间时。我们将通过分析一个实际案例，详细阐述如何正确配置JWT过期时间，并提供一套系统化的排查方法，包括验证生成令牌的有效载荷（payload）和检查关键参数的传递，确保令牌行为符合预期。

引言：JWT与过期时间的重要性

JSON Web Token (JWT) 作为一种紧凑、URL安全的令牌格式，广泛应用于认证和授权机制中。其核心功能之一是包含过期时间（exp claim），这对于维护会话安全和资源管理至关重要。正确设置和管理JWT的过期时间，可以有效防止令牌被长期滥用，并强制用户定期重新认证。然而，开发者在使用jsonwebtoken等库时，有时会遇到过期时间设置不生效的问题，尤其是在动态决定过期时长（例如“7天”或“7小时”）的场景下。

问题场景描述

在一个Node.js应用程序中，我们通常会根据用户操作或偏好来动态设置JWT的过期时间。例如，一个“记住我”功能可能需要更长的会话时间（如7天），而普通登录则可能只需要较短的会话时间（如7小时）。

以下是一个典型的JWT生成函数和登录处理函数的代码示例：

// tokenService.js
const jwt = require("jsonwebtoken");
/**
* 生成认证JWT令牌
* @param {string} _id - 用户ID
* @param {string} name - 用户名
* @param {string} lastName - 用户姓氏
* @param {string} email - 用户邮箱
* @param {boolean} isAdmin - 是否为管理员
* @param {boolean} doNotLogout - 是否延长会话（记住我）
* @returns {string} 生成的JWT令牌
*/
const generateAuthToken = (_id, name, lastName, email, isAdmin, doNotLogout) => {
// 根据doNotLogout参数决定过期时间
const expiresIn = doNotLogout ? "7d" : "7h"; // '7d' for 7 days, '7h' for 7 hours
return jwt.sign(
{ _id, name, lastName, email, isAdmin },
process.env.JWT_SECRET_KEY, // 从环境变量获取密钥
{ expiresIn: expiresIn } // 设置过期时间
);
};
module.exports = { generateAuthToken };

// authController.js
const { generateAuthToken } = require("./tokenService");
const User = require("../models/User"); // 假设存在User模型
const { comparePasswords } = require("../utils/helpers"); // 假设存在密码比较函数
const loginUser = async (req, res, next) => {
try {
const { email, password, doNotLogout } = req.body; // 从请求体获取doNotLogout
if (!email || !password) {
return res.status(400).json({ error: "All input fields are required" });
}
const user = await User.findOne({ email: email }).orFail(); // 查找用户
if (user && comparePasswords(password, user.password)) {
let cookieParams = {
httpOnly: true,
secure: process.env.NODE_ENV === "production", // 生产环境使用HTTPS
sameSite: "strict",
};
// 如果doNotLogout为true，则设置cookie的maxAge为7天
if (doNotLogout) {
cookieParams = { ...cookieParams, maxAge: 1000 * 60 * 60 * 24 * 7 };
}
// 生成JWT令牌并将其设置为HTTP-only cookie
return res
.cookie(
"access_token",
generateAuthToken(
user._id,
user.firstname,
user.lastName,
user.email,
user.isAdmin,
// 关键：确保doNotLogout参数正确传递给generateAuthToken
doNotLogout
),
cookieParams
)
.status(200)
.json({
_id: user._id,
name: user.firstname,
lastName: user.lastName,
email: user.email,
isAdmin: user.isAdmin,
doNotLogout,
});
} else {
return res.status(401).json({ error: "Wrong Credentials" });
}
} catch (err) {
next(err); // 错误处理
}
};

在这种设置下，当doNotLogout为true时，我们期望JWT的过期时间为7天；当doNotLogout为false时，过期时间为7小时。然而，有时会观察到即使doNotLogout为true，令牌仍然在7小时后失效。

深入排查与验证

当JWT过期时间不符合预期时，最核心的排查方法是直接检查生成的JWT令牌本身。

1. 验证JWT令牌的exp字段jsonwebtoken库在生成令牌时，会根据expiresIn选项计算出一个Unix时间戳（秒），并将其作为exp（expiration time）字段添加到JWT的有效载荷（payload）中。这个exp字段才是JWT真正过期时间的权威来源。

   • 如何验证：

     1. 获取一个实际生成的JWT令牌（例如，从浏览器的开发者工具中复制access_token cookie的值）。
     2. 访问在线JWT解码工具，如 jwt.io。
     3. 将你的JWT令牌粘贴到左侧的“Encoded”区域。
     4. 在中间的“Payload”区域，查找exp字段。jwt.io会自动将其转换为可读的日期时间格式。

   • 分析结果：

     

     美间AI

     美间AI：让设计更简单

     
     45

     查看详情
     

     • 如果exp字段显示的时间与你期望的7天（或7小时）后相符，那么说明generateAuthToken函数本身工作正常，JWT的过期时间设置是正确的。
     • 如果exp字段显示的时间总是7小时后，即使你期望是7天，那么问题可能出在doNotLogout参数的传递或其值在generateAuthToken函数内部的判断上。

2. 检查doNotLogout参数的传递

   在上述代码中，doNotLogout参数在loginUser函数中从req.body获取，并随后传递给generateAuthToken函数。任何环节的错误都可能导致expiresIn变量被错误赋值。

   • 客户端发送的数据：确认前端在发送登录请求时，doNotLogout字段的值是否正确（true或false）。例如，如果前端发送的是字符串”true”而不是布尔值true，在某些情况下可能会导致问题（尽管JavaScript中的if (“true”)仍为真）。
   • req.body的解析：确保你的Express应用配置了正确的body-parser中间件，能够正确解析JSON或URL编码的请求体。
   • 参数传递链：在loginUser函数中，确保generateAuthToken的最后一个参数确实是来自req.body的doNotLogout变量。例如，如果误传了user.doNotLogout（这可能是用户数据库中的一个旧值或默认值），而不是当前请求体中的值，就会导致问题。在提供的代码中，这一点是正确的：generateAuthToken(…, doNotLogout)。

3. 区分JWT过期与Cookie过期

   需要明确区分JWT内部的exp声明与HTTP Cookie的maxAge属性。

   • JWT exp：这是令牌本身的过期时间，由签名服务器设置，并在后续验证令牌时由服务器端检查。一旦JWT过期，即使Cookie仍然存在，服务器也会拒绝该令牌。
   • Cookie maxAge：这是浏览器应该保存Cookie的最长时间。当maxAge过期时，浏览器会自动删除Cookie。

   在示例代码中，loginUser函数正确地为doNotLogout为true的情况设置了cookieParams.maxAge为7天。这与JWT的7天过期时间保持一致，是良好的实践。然而，即使Cookie的maxAge很长，如果JWT本身在7小时后过期，用户仍然会在7小时后遇到授权失败。

结论与最佳实践

根据对代码的分析和常见问题的排查经验，jsonwebtoken库处理”7d”和”7h”这样的字符串作为expiresIn选项是完全正确的。如果遇到过期时间不生效的问题，核心原因通常不在于库本身，而在于以下两点：

1. doNotLogout参数在生成令牌时未能正确传递其期望值。
2. 对JWT的exp声明存在误解，或者未通过工具实际验证令牌的有效载荷。

排查步骤总结：

1. 获取问题令牌：从实际环境中获取一个你认为过期时间有问题的JWT。
2. 使用jwt.io解码：将令牌粘贴到jwt.io，检查Payload部分的exp字段，确认其显示的过期时间是否符合你的预期。
3. 调试doNotLogout：在generateAuthToken函数内部，打印expiresIn变量的值，确认它是否根据doNotLogout的值正确地设置为”7d”或”7h”。
4. 检查参数来源：在loginUser函数调用generateAuthToken之前，打印doNotLogout参数的值，确保它与用户请求中的意图一致。

通过这些系统化的排查步骤，你将能够迅速定位JWT过期时间设置不生效的根本原因，并确保你的认证系统按照预期运行。此外，保持jsonwebtoken和Node.js版本更新，也有助于避免潜在的兼容性问题。

原文来自：www.php.cn