如何修复 JWT 认证中空 Cookie 导致 Fetch 请求挂起的问题

修复 JWT 认证中空 Cookie 导致 Fetch 请求挂起

在 JWT 认证流程中，若中间件未检查请求是否携带 token Cookie，当客户端未发送 cookie 时，jwt.verify() 的回调可能不会执行，导致响应无法发送，Fetch 请求将永久处于 pending 状态。本文将提供完整的修复方案与最佳实践。

在使用 JWT 实现基于 Cookie 的身份认证时，开发者常会遇到一个隐蔽的问题：未对请求中是否携带有效 token 进行显式判断。问题的核心在于，`jwt.verify()` 是一个异步函数，它仅在接收到有效的 token 字符串时才会触发其回调函数。如果 `req.cookies.token` 的值为 `undefined` 或空字符串，`jsonwebtoken` 库内部不会执行回调，也不会抛出同步错误。这将导致服务器端的 `res.json()` 或 `res.status()` 永远不会被调用，响应因此被遗漏。前端发起的 Fetch 请求将一直等待响应，处于 pending 状态，直至最终超时失败。

正确的解决方案是什么？关键在于：在调用 `jwt.verify()` 之前，必须主动检查 token 是否存在且内容非空。这类似于在安检前先确认旅客持有有效凭证，而不是直接进行安检操作。

import jwt from "jsonwebtoken";
export const isAuthenticated = (req, res) => {
  const token = req.cookies?.token;
  //  关键防御步骤：检查 token 是否缺失或为空
  if (!token || typeof token !== 'string' || token.trim() === '') {
    return res.status(401).json({
      ok: false,
      message: 'Authentication token is missing or invalid.'
    });
  }
  //  安全地将 token 传递给验证函数
  jwt.verify(token, process.env.SECRET, (err, user) => {
    if (err) {
      // 常见错误包括：token 过期、签名不匹配、格式非法等
      return res.status(403).json({
        ok: false,
        message: 'Invalid or expired authentication token.',
        error: err.name // 可选：用于调试（生产环境建议隐藏）
      });
    }
    //  验证成功：返回用户信息（注意：user 是解码后的 payload，不含密码等敏感字段）
    res.status(200).json({ ok: true, user });
  });
};

在实施上述方案时，有几个关键细节需要注意，它们直接影响代码的稳定性和安全性：

• 注意响应方法的调用顺序：避免链式调用如 `.json().status()`。因为 `res.json()` 会立即发送响应并结束本次请求处理，之后再调用 `.status(200)` 将无效，并可能引发 “Cannot set headers after they are sent” 错误。标准做法是始终先调用 `res.status()` 设置状态码，再调用 `res.json()` 发送 JSON 数据。
• 确保 Cookie 安全配置与前端环境匹配：如果后端设置了 `sameSite: ‘none‘` 和 `secure: true`，前端必须通过 HTTPS 协议访问，并且在发起跨域请求时，必须显式设置 `credentials: ‘include‘`。
• 前端 Fetch 示例（确保携带 Cookie）：

  fetch('/api/auth/isAuthenticated', {
    method: 'GET',
    credentials: 'include' //  必须启用，否则浏览器不会发送 Cookie
  }).then(res => {
    if (res.ok) return res.json();
    throw new Error(`HTTP ${res.status}`);
  }).then(data => console.log('Auth OK:', data))
  .catch(err => console.error('Auth failed:', err));

• 利用日志辅助排查问题：在开发阶段，可以在认证中间件的开头添加 `console.log(‘Token received:‘, token)`。这有助于快速确认 Cookie 是否成功到达服务端，是定位问题的有效工具。

总而言之，构建健壮的 JWT Cookie 认证体系，起点在于对输入数据的严格校验。一个基本原则是：始终假设客户端可能发送任何形式的凭证——包括无效的，或者根本不发送。在将 token 送入解码流程之前，就完成其存在性与基本格式的检查。这种做法不仅能彻底解决请求挂起的问题，也是防范未授权访问和服务端异常的重要基础。