RedwoodJS Supabase 认证回跳修复解析restoreAuthState 如何保留自定义搜索参数【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本文基于 RedwoodJS 仓库中的变更记录.changesets/12102.md展开。该变更修复了 Supabase 认证集成中一个隐蔽但影响真实的 bug当用户通过 OAuth、Magic Link 或密码找回流程被重定向回应用时restoreAuthState()会把 URL 上所有的搜索参数包括开发者自定义的业务参数一并清空。修复之后只有 Supabase 自己管理的认证参数会被清理其余参数得以完整保留。读完本文你将理解该 bug 的成因、修复的底层实现源码位于 supabase.ts以及如何在 RedwoodJS 项目中正确应对认证回调 URL 的参数处理。背景Supabase 认证回调为什么要恢复状态在 RedwoodJS 中集成 Supabase 认证后前端登录流程通常是这样的应用调用useAuth()提供的logIn()由 Supabase 客户端负责跳转到第三方身份提供方如 GitHub OAuth、发送 Magic Link 邮件或一次性密码OTP。用户完成认证后Supabase 会把用户重定向回你的应用页面并在 URL 上携带一组认证凭证参数——典型的有access_token、refresh_token、token_type、expires_in、expires_at。此时前端需要从 URL 中取出这些令牌、在 Supabase 客户端里重建会话。在 RedwoodJS 的 Supabase 集成中这个动作由restoreAuthState()完成。正如源码注释所说supabase.tsRestore Redwood authentication state when an OAuth or magiclink callback redirects back to site with access token by restoring the Supabase auth session.该方法会初始化 Supabase 客户端会话从 URL 或存储中恢复官方建议在收到认证重定向OAuth、Magic Link、密码找回等的报错或返回时手动调用它。注意Supabase 客户端在实例化时也会自动调用一次会话恢复逻辑。问题restoreAuthState 把用户参数一并抹掉了变更记录.changesets/12102.md清楚描述了 bug 的成因We call therestoreAuthState()function in the Supabase auth integration when the user gets redirected back to the app. The problem was that this would completely wipe out all search parameters, including user-defined ones.也就是说旧实现的问题不在于清理认证参数本身——这是必要的因为把这些敏感令牌留在地址栏里既不美观也不安全——而在于清理方式过于粗暴它把整个 URL 的查询串清空连业务方自定义的参数例如?redirect_to/dashboard、?utm_sourcenewsletter或营销归因参数也一并删除。这在真实场景中会造成两类可见的问题业务流程断裂例如登录页带着?next/account发起 OAuth回跳后该参数丢失应用无法继续执行登录后跳转到目标页的逻辑追踪与体验信息丢失渠道来源、AB 实验分组等参数被清空影响数据分析与个性化体验。修复方案只删除 Supabase 管理的参数修复的核心思路一句话概括从清空全部查询参数改为仅删除 Supabase 自己管理的参数。改动后的restoreAuthState()实现位于 supabase.ts关键逻辑如下restoreAuthState: async () { try { const { data } await supabaseClient.auth.refreshSession() if (middleware) { if (data.session) { setAuthProviderCookie() } else { expireAuthProviderCookie() } } // Clean up OAuth callback parameters while preserving other search params const currentUrl new URL(window.location.href) const authParams [ access_token, refresh_token, token_type, expires_in, expires_at, ] let hasAuthParams false // Remove only Supabase auth-related parameters authParams.forEach((param) { if (currentUrl.searchParams.has(param)) { currentUrl.searchParams.delete(param) hasAuthParams true } }) // Only modify URL if we actually removed auth parameters if (hasAuthParams) { const cleanUrl currentUrl.pathname (currentUrl.search || ) window.history.replaceState({}, document.title, cleanUrl) } } catch (error) { console.error(error) } return }实现细节逐段解读会话恢复supabaseClient.auth.refreshSession()负责从 URL 中的令牌或本地存储重建会话。data.session存在则说明登录成功。中间件模式下的 cookie 同步在RWJS_EXP_STREAMING_SSR流式 SSR开启时RedwoodJS 会走createMiddlewareAuth()路径见 supabase.ts此时restoreAuthState会依据会话是否有效来设置或过期auth-providercookie——这个 cookie 是服务端中间件识别当前认证提供方的依据。精确删除通过new URL(window.location.href)解析当前地址用URLSearchParams的has()/delete()逐个移除白名单内的五个认证参数。按需改写地址只有确实删除了认证参数hasAuthParams true时才调用window.history.replaceState()改写地址栏避免无谓的 history 操作改写时保留pathname和剩余的search不携带 hash。这种白名单 按需改写的做法同时兼顾了三点敏感令牌及时从地址栏移除、自定义参数原样保留、URL 不被多余地改动。白名单里的五个参数从哪来修复中硬编码的参数列表const authParams [ access_token, refresh_token, token_type, expires_in, expires_at, ]这五个正是 Supabase 的 Auth 服务在隐式授权implicit flow回调里返回的标准令牌参数expires_at为 Supabase 特有用于计算访问令牌过期时间。它们由 Supabase 官方管理删除它们不会影响业务逻辑而除此之外的任意参数next、redirect_to、state、error、error_description等都不在白名单中会被保留。测试如何验证这一行为该修复并非没有防线。仓库中的中间件模式测试 supabase.middleware.test.tsx 覆盖了认证 cookie 的完整生命周期其中明确列出的测试清单见文件 L85-L92包含登录前未认证getCurrentUser从中间件获取signup 与 login含 password / oauth / otp / id_token / sso 五种方式后设置auth-providercookielogout 后过期该 cookierestoreAuthState中根据会话状态设置或过期 cookie自定义useHasRole、useCurrentUser钩子生效。测试通过cookieSetSpy断言 cookie 的内容与DEFAULT_SUPABASE_COOKIE_OPTIONS来自supabase/ssr保持一致——例如Max-Age31536000000、Path/、SameSiteLax见 L392-L410删除时则断言Max-Age-1见 L412-L421。这些断言间接保证了restoreAuthState在中间件模式下对认证状态的同步是正确且可回归验证的。在 RedwoodJS 项目中落地 Supabase 认证要复现并受益于该修复你需要在 RedwoodJS 项目中启用 Supabase 认证。完整步骤参见 docs/docs/auth/supabase.md核心要点如下。1. 初始化yarn rw setup auth supabase该命令会安装依赖、写入模板文件并完成必要的代码修改。生成的 web 端认证代码位于web/src/auth.ts模板见 setup/src/templates/web/auth.ts.template。2. 配置环境变量在.env中配置 Supabase 的项目信息SUPABASE_URLhttps://your-project.supabase.co SUPABASE_KEYyour-anon-public-key SUPABASE_JWT_SECRETyour-jwt-secret同时在redwood.toml中把 web 端需要访问的变量列入白名单[web] # ... includeEnvironmentVariables [SUPABASE_URL, SUPABASE_KEY]3. 各认证方式的调用形态RedwoodJS 统一通过useAuth()的logIn方法触发登录用authMethod字段声明认证方式详见 docs/docs/auth/supabase.mdconst { logIn } useAuth() // 邮箱 密码 await logIn({ authMethod: password, email: exampleemail.com, password: example-password }) // OAuth 第三方 await logIn({ authMethod: oauth, provider: github }) // 密码lessOTP / Magic Link await logIn({ authMethod: otp, email: exampleemail.com }) // ID Token await logIn({ authMethod: id_token, provider: apple, token: cortland-apple-id-token }) // 企业 SSO await logIn({ authMethod: sso, providerId: sso-provider-identity-uuid, domain: example.com })这些authMethod在createAuthImplementation的login方法里通过switch分发到对应的 Supabase 客户端 API见 supabase.ts类型定义见同文件的SignInWithOAuthOptions、SignInWithPasswordOptions等L25-L44。4. 回跳场景下的表现修复生效后无论用户走 OAuth 还是 Magic Link回跳 URL 中的自定义参数如?redirect_to/accountfromlanding都会在restoreAuthState执行后被完整保留只有access_token等五个认证参数被清除。这让你可以在回跳页例如路由守卫、useEffect中继续读取这些参数做跳转、埋点等业务处理而无需担心被认证流程顺手清空。小结Bug 根因restoreAuthState()此前将回调 URL 的所有搜索参数整体清空误伤了开发者自定义参数修复手段改为白名单式清理仅删除 Supabase 管理的access_token、refresh_token、token_type、expires_in、expires_at并通过replaceState按需改写地址栏源码位置packages/auth-providers/supabase/web/src/supabase.tsrestoreAuthState见 L275-L317验证中间件模式测试 supabase.middleware.test.tsx 覆盖了 cookie 同步等回归场景。如果你在集成 Supabase 认证时发现回跳后自定义参数丢失可以先确认使用的 RedwoodJS 版本是否包含该修复对应变更记录 .changesets/12102.md再检查restoreAuthState的实现版本。若需进一步了解 RedwoodJS 认证的整体设计API 侧getCurrentUser、中间件模式等可参考 docs/docs/authentication.md。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考