AWS Amplify Next.js 适配器中的服务端 Cookie 行为解析

核心问题概述

在使用 AWS Amplify 的 Next.js 适配器时，开发者需要注意一个关键行为：当在 Next.js 服务端操作（如 Server Actions）中执行 fetchAuthSession 方法时，如果触发了令牌刷新，系统会自动设置 Cookie。这些服务端设置的 Cookie 会采用默认属性值，这可能与客户端配置的 Cookie 存储策略产生冲突。

技术背景

AWS Amplify 为 Next.js 应用提供了专门的适配器模块 @aws-amplify/adapter-nextjs，用于简化认证流程的集成。在认证过程中，系统会使用 Cookie 来存储和管理身份验证令牌。

服务端与客户端的 Cookie 差异

1. 服务端默认行为：

   • 当在服务端触发令牌刷新时，设置的 Cookie 会使用默认属性
   • 这些默认属性可能包括默认的 domain、path 等值

2. 客户端自定义配置：

   • 开发者通常会在客户端使用 CookieStorage 进行自定义配置
   • 可以设置 domain、secure、path、sameSite 和 expires 等属性

潜在问题场景

当服务端设置的 Cookie 属性与客户端配置不匹配时，会导致以下问题：

1. 登出操作失效：

   • 客户端登出时无法清除服务端设置的不匹配 Cookie
   • 这些残留的 Cookie 会持续存在

2. 认证流程异常：

   • 陈旧的 Cookie 会反复触发 tokenRefresh_failure 事件
   • 最终导致用户无法正常登录系统

解决方案演进

AWS Amplify 团队已经针对这一问题提供了两种解决方案：

1. 文档说明（初始方案）

最初通过文档说明这一行为，提示开发者注意服务端设置的 Cookie 会采用默认值，无法在服务端进行属性定制。

2. 运行时配置（最新方案）

在最新版本中（aws-amplify@6.13.1 和 @aws-amplify/adapter-nextjs@1.5.1），引入了服务端 Cookie 属性配置能力：

import { createServerRunner } from '@aws-amplify/adapter-nextjs';

export const { runWithAmplifyServerContext } = createServerRunner({
  config: outputs,
  runtimeOptions: {
    cookies: {
      domain: ".myapp.com",
      maxAge: 3600, // 1小时
      sameSite: "strict",
    },
  },
});

注意：

• secure 属性不能直接配置
• 需要确保服务端和客户端的 Cookie 配置保持一致

最佳实践建议

1. 版本升级：

   • 建议升级到支持服务端 Cookie 配置的最新版本

2. 配置一致性：

   • 确保服务端和客户端的 Cookie 配置参数保持一致
   • 特别注意 domain 和 sameSite 等关键属性

3. 错误处理：

   • 实现完善的错误处理机制，特别是针对 tokenRefresh_failure 事件
   • 考虑添加自动清理无效 Cookie 的逻辑

总结

AWS Amplify 的 Next.js 适配器在服务端认证流程中的 Cookie 处理行为是一个需要开发者特别注意的技术细节。通过理解这一机制并合理配置服务端和客户端的 Cookie 参数，可以避免认证流程中的各种异常问题，为用户提供更稳定可靠的认证体验。