Shopify Hydrogen开发中解决Customer Account API授权问题

问题背景

在Shopify Hydrogen框架开发过程中，许多开发者在使用Customer Account API时遇到了"Bad request: Unauthorized"错误，控制台显示"Customer Account API Error: The session state does not match the state parameter"的提示信息。这个问题通常出现在使用Ngrok进行本地开发时，特别是在从较旧版本的Hydrogen升级到2024.7.x版本后。

错误原因分析

这个授权问题的根本原因在于Hydrogen框架在2024.7.x版本中引入了一个重要的会话管理变更。新版本修改了会话提交模式，要求开发者对会话管理进行相应的调整。具体表现为：

1. 会话状态不匹配：客户端和服务器端的会话状态不一致
2. 安全策略限制：WebSocket连接可能被内容安全策略(CSP)阻止
3. 会话提交时机：传统的在路由中提交会话的方式不再适用

解决方案

1. 实现会话pending状态

首先需要在会话类中添加isPending状态跟踪：

export class AppSession implements HydrogenSession {
  public isPending = false;

  get unset() {
    this.isPending = true;
    return this.#session.unset;
  }

  get set() {
    this.isPending = true;
    return this.#session.set;
  }

  commit() {
    this.isPending = false;
    return this.#sessionStorage.commitSession(this.#session);
  }
}

2. 修改响应头处理

在服务器入口文件中，需要根据会话状态自动设置响应头：

export default {
  async fetch(request: Request): Promise<Response> {
    try {
      const response = await handleRequest(request);

      if (session.isPending) {
        response.headers.set('Set-Cookie', await session.commit());
      }

      return response;
    } catch (error) {
      // 错误处理
    }
  },
};

3. 移除路由中的会话提交

不再需要在各个路由中手动提交会话：

export async function loader({context}: LoaderFunctionArgs) {
  return json({}); // 移除了手动设置Set-Cookie的代码
}

4. 内容安全策略调整

对于使用Ngrok的开发环境，还需要在内容安全策略中添加WebSocket连接的白名单：

createContentSecurityPolicy({
  connectSrc: [
    "'self'",
    "wss://your-ngrok-domain.app:*" // 替换为实际的Ngrok域名
  ],
  // 其他策略...
});

注意事项

1. 确保所有环境变量已正确配置，特别是PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID和PUBLIC_CUSTOMER_ACCOUNT_API_URL
2. 使用最新版本的Hydrogen CLI工具
3. 对于生产环境部署，需要确保会话存储配置正确
4. 如果使用自定义会话存储实现，需要确保其与新的会话管理模式兼容

总结

Shopify Hydrogen框架2024.7.x版本引入的会话管理变更虽然带来了更好的安全性和性能，但也需要开发者相应调整代码实现。通过正确实现会话pending状态、调整响应头处理方式以及更新内容安全策略，可以有效解决Customer Account API的授权问题。这些修改不仅解决了当前的错误，也为应用提供了更健壮的会话管理机制。