本教程详细阐述了在 nuxt3 应用中，如何通过 nuxt apollo 客户端同时管理多重认证请求头（如 jwt 和 woocommerce 会话）。当 nuxt apollo 的默认配置无法满足复杂认证需求时，我们将学习如何自定义 apollo client 实例，并通过手动注入的方式，完全控制请求头、会话管理和认证逻辑，从而实现灵活且强大的认证机制。
Nuxt3 Apollo 中多重认证请求头的挑战
在开发基于 Nuxt3、WPGraphQL 和 WooCommerce 的无头应用程序时，一个常见的挑战是需要同时处理多种认证机制。例如，你可能需要一个 woocommerce-session 请求头来管理访客购物车会话，同时又需要一个 Authorization: Bearer
Nuxt Apollo 模块提供了一套便捷的认证配置选项，如 authType 和 authHeader。然而，这些选项通常旨在支持单一的认证令牌类型和请求头。当试图同时管理多个动态变化的请求头时，Nuxt Apollo 的默认 apollo:auth 钩子和 nuxt.config.ts 中的客户端配置可能会导致冲突，使得你无法灵活地设置和更新所有必要的请求头。这种限制使得在需要同时维护用户登录状态和访客购物车会话的场景下，默认配置显得力不从心。
自定义 Apollo Client 实例以实现灵活认证
解决上述问题的核心在于完全掌控 Apollo Client 的实例化过程，绕过 Nuxt Apollo 模块的默认认证处理，转而使用自定义的 Apollo Link 链来构建客户端。
1. Nuxt Apollo 插件 (apollo.js) 配置
我们将创建一个 Nuxt 插件 (plugins/apollo.js) 来初始化和配置我们的 Apollo Client。这个插件将负责：
- 定义 GraphQL HTTP 端点。
- 通过 setContext 动态注入多个认证请求头。
- 通过 ApolloLink 的 afterware 机制处理响应头，例如更新会话 ID。
- 最终，手动将自定义的 Apollo Client 实例注入到 Nuxt 应用上下文中。
import {
createHttpLink,
ApolloLink,
from,
InMemoryCache,
ApolloClient
} from '@apollo/client/core';
import { setContext } from '@apollo/client/link/context';
import { provideApolloClient } from '@vue/apollo-composable'; // 用于 Vue 组合式 API
export default defineNuxtPlugin((nuxtApp) => {
// 从 Cookie 中获取 JWT 令牌和 WooCommerce 会话 ID
const wooJWT = useCookie('woo-jwt');
const wooSession = useCookie('woo-session', {
maxAge: 86_400, // 会话 Cookie 有效期，例如 1 天
sameSite: 'lax' // 跨站请求策略
});
const config = useRuntimeConfig();
// 1. HTTP Link: 定义 GraphQL 后端地址
const httpLink = createHttpLink({
uri: config.public.graphqlURL,
});
// 2. Auth Link: 动态设置认证请求头
// 使用 setContext 确保在每次请求前检查并设置最新的 JWT 和会话 ID
const authLink = setContext(async (_, { headers }) => {
return {
headers: {
...headers,
// 如果存在 JWT，则添加 Authorization 请求头
authorization: wooJWT.value ? `Bearer ${wooJWT.value}` : '',
// 如果存在 WooCommerce 会话 ID，则添加 woocommerce-session 请求头
'woocommerce-session': wooSession.value
? `Session ${wooSession.value}`
: ''
}
};
});
// 3. Afterware Link: 处理来自响应的请求头
// 监听响应头，例如更新 WooCommerce 会话 ID
const afterware = new ApolloLink((operation, forward) =>
forward(operation).map((response) => {
const context = operation.getContext();
const {
response: { headers }
} = context;
const session = headers.get('woocommerce-session');
if (process.client && session) {
// 如果响应头中包含新的会话 ID，则更新本地 Cookie
if (session !== wooSession.value) {
wooSession.value = session;
}
}
return response;
})
);
// 4. 缓存实现
const cache = new InMemoryCache();
// 5. 创建 Apollo Client 实例
// 将 authLink, afterware, httpLink 按顺序链式组合
const apolloClient = new ApolloClient({
link: from([authLink, afterware, httpLink]),
cache
});
// 如果需要直接在 Vue 组合式 API 中使用，可以保留此行
// 否则，通过 nuxtApp._apolloClients.default 赋值已经足够
provideApolloClient(apolloClient);
/**
* 关键步骤：
* 移除 Nuxt Apollo 的 'apollo:auth' 钩子，
* 并手动将自定义的 apolloClient 实例赋值给 Nuxt 应用的默认 Apollo 客户端。
* 这将完全覆盖 Nuxt Apollo 模块的默认客户端配置，确保我们的自定义设置生效。
*/
// nuxtApp.hook('apollo:auth', ({ client, token }) => {
// // 此钩子应被移除或注释，因为它与自定义 Auth Link 冲突
// // token.value = wooSession.value;
// });
nuxtApp._apolloClients.default = apolloClient;
});在上述代码中，authLink 使用 setContext 来动态地为每个请求添加 Authorization 和 woocommerce-session 这两个请求头。afterware 则负责从响应中提取 woocommerce-session 头并更新本地 Cookie。最关键的是，通过 nuxtApp._apolloClients.default = apolloClient; 这一行，我们直接用自定义的客户端替换了 Nuxt Apollo 模块默认创建的客户端，从而获得了完全的控制权。
2. Nuxt 配置文件 (nuxt.config.ts) 调整
由于我们已在插件中完全自定义了 Apollo Client，nuxt.config.ts 中的 apollo 模块配置应进行精简。特别是，与认证相关的 authType、authHeader 和 tokenStorage 等选项应被移除或注释掉，以避免与自定义逻辑产生冲突。
import { defineNuxtConfig } from 'nuxt/config';
export default defineNuxtConfig({
// ... 其他 Nuxt 配置
apollo: {
// 移除或注释掉所有与认证相关的全局配置，
// 因为认证逻辑已完全在 apollo.js 插件中处理。
// authType: 'Session',
// authHeader: 'woocommerce-session',
// tokenStorage: 'cookie',
// tokenName: 'woocommerce-session',
clients: {
default: {
// 仅保留 HTTP 端点配置，确保与插件中的 httpLink.uri 一致
httpEndpoint: process.env.PUBLIC_GRAPHQL_URL,
httpLinkOptions: {
credentials: 'include' // 如果需要发送 Cookie，请保留此选项
}
// 移除或注释掉客户端特定的 JWT 认证配置
// authType: 'Bearer',
// authHeader: 'Authorization',
// tokenStorage: 'cookie'
}
}
}
});通过以上调整，nuxt.config.ts 的 apollo 配置将变得非常简洁，主要用于定义默认客户端的 HTTP 端点和其他非认证相关的通用设置。
注意事项与总结
- 完全控制与责任： 这种方法赋予了你对 Apollo Client 的完全控制权，但也意味着你需要自行管理所有认证逻辑，包括令牌的存储、刷新、过期处理以及请求头的动态设置。
- Cookie 管理： 使用 useCookie 管理 JWT 和会话 ID 是 Nuxt3 中推荐的方式，它能很好地支持 SSR (Server-Side Rendering) 和 CSR (Client-Side Rendering) 场景。确保 Cookie 的 maxAge、sameSite 和 secure 属性设置正确，以保障安全性。
- 错误处理： 在 authLink 中，你可以添加额外的逻辑来处理令牌过期的情况，例如重定向到登录页或尝试刷新令牌。
- 适用场景： 当 Nuxt Apollo 模块的内置认证机制无法满足你的复杂需求（例如需要多个动态请求头、复杂的令牌刷新流程或与特定后端系统深度集成）时，这种自定义方法非常有效。对于简单的单令牌认证场景，Nuxt Apollo 的默认配置可能更为便捷。
通过上述步骤，你可以在 Nuxt3 应用中成功地集成 Nuxt Apollo，并灵活地处理多重认证请求头，无论是访客会话管理还是用户登录后的 JWT 认证，都能在一个 Apollo Client 实例中无缝协作。这种方法提供了一个强大且可扩展的解决方案，适用于复杂的无头电商或内容管理系统。
