KeystoneJS 6外部前端调用AuthenticateUserWithPassword后无有效会话问题

核心问题本质 #

你碰到的问题是跨域场景下的会话凭证传递规则差异：AdminUI属于同域请求，浏览器会自动处理会话凭证；而外部前端是跨域请求，必须满足跨域凭证传递的特定要求，Keystone才能识别并加载会话。

必须配置的关键项 #

• Fetch请求强制携带凭证
  调用GraphQL API的fetch请求必须添加credentials: 'include'选项，这会让浏览器自动携带keystonejs-session cookie（包括HttpOnly类型的cookie，手动在header里写Cookie字段无法获取HttpOnly cookie）。示例代码：

  fetch('https://your-keystone-instance.com/api/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include', // 核心配置
    body: JSON.stringify({ query: '你的查询/变更内容' }),
  });
  

• Keystone端配置CORS允许凭证
  在Keystone的配置文件中，必须开启CORS的凭证允许，并指定允许的前端域名：

  // keystone.ts
  export default config({
    server: {
      cors: {
        origin: ['https://your-frontend-domain.com'], // 替换为你的前端实际域名
        credentials: true, // 必须设为true，允许跨域传递凭证
      },
    },
    // 其他配置项...
  });
  

• 调整Session Cookie的SameSite属性
  Keystone默认的Session Cookie SameSite属性是Lax，仅支持同域或有限跨域场景。跨域场景下需要设置为None，同时必须开启Secure（仅HTTPS环境有效，本地开发可临时关闭）：

  // keystone.ts
  export default config({
    session: {
      cookie: {
        sameSite: 'none',
        secure: process.env.NODE_ENV === 'production', // 生产环境强制HTTPS
        maxAge: 60 * 60 * 24 * 30, // 会话有效期30天
        path: '/',
      },
    },
    // 其他配置项...
  });
  

常见误区排查 #

1. 不要尝试手动在请求头中添加Cookie: keystonejs-session=xxx：Keystone默认生成的会话cookie是HttpOnly的，前端JS无法读取该cookie的值，手动添加的方式完全无效，必须依赖credentials: 'include'让浏览器自动处理。
2. 本地开发用HTTP协议时，浏览器可能会拒绝SameSite=None的cookie，此时可以临时将sameSite设为Lax，并确保前端和Keystone在同一主域下（比如前端用localhost:3000，Keystone用localhost:3001，浏览器视为同域）。

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