NodeJS Koa设置JWT刷新令牌HttpOnly Cookie无效求助

先澄清一个误区：设置后立即get返回undefined是正常的 #

ctx.cookies.get('jwt')是从当前请求的Request Headers里读取Cookie值，而你通过ctx.cookies.set()设置的是要写入Response Headers的Set-Cookie，当前请求的请求头里本来就没有这个Cookie，所以立即打印肯定是undefined，这个不是问题，不用纠结。

核心问题：浏览器不存储Cookie的常见原因及解决办法 #

1. 跨域场景下的CORS配置缺失 #

如果前端和后端不在同一域名/端口下，必须做以下配置：

• 后端Koa的CORS中间件（比如@koa/cors）要开启允许携带凭证：

const cors = require('@koa/cors');
app.use(cors({
  credentials: true, // 允许前端携带Cookie
  origin: 'http://你的前端域名:端口', // 不能用*，必须指定具体域名
}));

• 前端请求时要开启凭证携带：
  • Axios：axios.post('/login', data, { withCredentials: true })
  • Fetch：fetch('/login', { method: 'POST', credentials: 'include', ... })

2. Cookie的路径（path）限制 #

默认情况下，Koa设置的Cookie路径是当前请求的路径（比如login接口是/api/login，则Cookie的path是/api），如果refresh接口不在这个路径下，就无法获取到Cookie。建议显式设置path: '/'，让整个域名下的接口都能访问：

ctx.cookies.set("jwt", session[1], {
  httpOnly: true,
  path: '/', // 关键配置
  maxAge: 7 * 24 * 60 * 60 * 1000, // 建议设置过期时间，比如7天
});

3. Secure与SameSite属性配置（生产/跨域场景） #

• 如果前端是HTTPS协议，必须设置secure: true，否则浏览器会拒绝存储HttpOnly Cookie；
• 跨域场景下，需要设置sameSite: 'None'，但这个属性必须和secure: true配合使用（本地localhost的HTTP环境部分浏览器例外）：

ctx.cookies.set("jwt", session[1], {
  httpOnly: true,
  path: '/',
  maxAge: 7 * 24 * 60 * 60 * 1000,
  secure: process.env.NODE_ENV === 'production', // 生产环境开启
  sameSite: process.env.NODE_ENV === 'production' ? 'None' : 'Lax',
});

4. 域名（domain）配置 #

如果前后端是子域名关系（比如前端是app.example.com，后端是api.example.com），需要设置domain: '.example.com'，让子域名共享Cookie：

ctx.cookies.set("jwt", session[1], {
  httpOnly: true,
  path: '/',
  domain: '.example.com', // 注意前面的点
  maxAge: 7 * 24 * 60 * 60 * 1000,
});

修改后的完整Login接口示例 #

const login = async (ctx) => {
  const { email, password } = ctx.request.body;
  const session = await userService.login(email, password);
  ctx.body = session[0];
  
  ctx.cookies.set("jwt", session[1], {
    httpOnly: true,
    path: '/',
    maxAge: 7 * 24 * 60 * 60 * 1000,
    secure: process.env.NODE_ENV === 'production',
    sameSite: process.env.NODE_ENV === 'production' ? 'None' : 'Lax',
  });
  
  // 此处无需打印，当前请求的请求头不存在该Cookie
  // console.log(ctx.cookies.get("jwt")); 
};
login.validationScheme = {
  body: {
    email: Joi.string().email(),
    password: Joi.string(),
  },
};

验证步骤 #

1. 登录请求后，查看浏览器Application面板的Cookie栏，确认是否存在jwt Cookie；
2. 调用refresh接口时，查看Request Headers里是否包含Cookie: jwt=xxx；
3. 如果还是不行，检查浏览器控制台的Console或Network面板，是否有Cookie被拦截的警告（比如SameSite、Secure相关）。

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