Wagmi SSR 在Next.js服务端重定向时的Cookie处理问题解析

问题背景

在使用Wagmi进行SSR(服务器端渲染)开发时，特别是在Next.js应用路由器(App Router)环境下，开发者按照官方文档指引使用cookieToInitialState函数从请求头中获取cookie来初始化状态。然而，当从服务端动作(server action)进行重定向时，会遇到cookie解析错误的问题。

问题现象

当开发者按照标准方式调用：

const initialState = cookieToInitialState(getConfig(), headers().get('cookie'))

在普通请求场景下工作正常，但在服务端动作重定向时，headers().get('cookie')返回的是经过编码的cookie字符串，导致cookieToInitialState函数解析失败，抛出JSON解析错误。

技术原理分析

1. Next.js服务端动作特性：Next.js的服务端动作在重定向时会自动对cookie进行编码处理，这是为了防止特殊字符导致传输问题。

2. Wagmi的cookie处理机制：cookieToInitialState函数期望接收的是原始的、未编码的cookie字符串，它会按照特定格式解析这些cookie来重建Wagmi的初始状态。

3. 编码冲突：当cookie被URI编码后，其中可能包含类似%7B这样的编码字符，这与JSON格式不兼容，导致解析失败。

解决方案

方案一：手动解码cookie

const initialState = cookieToInitialState(
  getConfig(), 
  decodeURIComponent(headers().get('cookie'))
)

这种方法简单直接，但需要开发者记住在服务端动作场景下进行额外处理。

方案二：使用Next.js的cookies API

Next.js 14提供了专门的cookies API，可以更可靠地获取cookie值：

const cookieStore = cookies()
const cookie = cookieStore
  .getAll()
  .map(c => `${c.name}=${c.value}`)
  .join('; ')

const initialState = cookieToInitialState(getConfig(), cookie)

这种方法更加规范，利用了Next.js提供的原生API，避免了手动处理编码问题。

最佳实践建议

1. 环境判断：在可能同时存在普通请求和服务端动作的场景下，可以增加环境判断逻辑，自动选择合适的cookie获取方式。

2. 封装工具函数：将cookie处理逻辑封装成工具函数，统一处理各种场景下的cookie获取和解析。

3. 错误边界处理：在cookie解析逻辑外层添加错误捕获，确保即使解析失败也不会导致整个应用崩溃。

总结

Wagmi与Next.js的深度集成带来了便利，但也需要注意框架特定行为带来的兼容性问题。理解Next.js对cookie的特殊处理机制，并采用适当的解决方案，可以确保SSR场景下的状态管理稳定可靠。对于长期项目，建议采用方案二的Next.js原生API方式，以获得更好的维护性和兼容性。