Wasp 自建邮箱认证 UI 完整指南从登录、注册验证到密码重置的实战实现【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本文是一份面向 Wasp0.18 版本开发者的实战指南讲解如何抛弃预置的 Auth UI通过wasp/client/auth提供的login、signup、verifyEmail、requestPasswordReset、resetPassword五个前端 action从零搭建一套完全自定义的邮箱认证界面覆盖登录、注册、邮箱验证、忘记密码与重置密码五大流程。读完本文你将掌握自建认证 UI 的全部代码骨架、每个 action 的参数契约与调用时机并理解其在 Wasp 生成代码中的底层实现原理。为什么需要自建认证 UI在 Wasp 中启用邮箱认证auth.methods.email后用户通过邮箱地址与密码登录。注册时 Wasp 会校验数据并发送验证邮件用户必须点击邮件中的验证链接后账户才会被激活此外用户还可以通过类似的流程重置密码。虽然 Wasp 提供了开箱即用的 Auth UI 组件LoginForm、SignupForm、VerifyEmailForm、ForgotPasswordForm、ResetPasswordForm但实际项目中经常需要与品牌视觉、交互细节完全一致的表单界面。此时有两种选择对预置组件做有限的样式定制改动空间有限完全自建 UI在自建代码中直接调用 Wasp 的 auth actions——这正是 Auth UI 组件在底层所做的只是把控制权交还给你。自建 UI 的核心原则只有一条界面、样式、交互完全由你掌控但登录/注册/验证/重置等关键动作必须通过wasp/client/auth导出的函数完成因为这些函数封装了与 Wasp 后端通信、会话初始化的全部细节。默认校验规则与流程概览在动手写代码之前先明确 Wasp 对邮箱认证的默认约束详见 auth 概述文档email不能为空且必须是合法的邮箱地址邮箱以大小写不敏感的方式存储password不能为空至少 8 个字符且必须包含数字。这些校验既作用于 Wasp 的 Auth UI也作用于通过wasp/client/auth调用的默认 actions。如果你使用自定义 auth actionsauth.methods.email之外的自研后端则需要自行执行校验。整个邮箱认证涉及 5 个客户端函数对应 5 个页面/交互场景函数触发场景成功后应做的事login({ email, password })用户登录跳转到应用主页等signup({ email, password })用户注册提示用户查收验证邮件verifyEmail({ token })用户点击邮件验证链接跳转到登录页requestPasswordReset({ email })用户忘记密码提示用户查收重置邮件resetPassword({ token, password })用户点击重置链接跳转到登录页完整示例src/pages/auth.tsx下面这份代码是自建 UI 的完整起点包含处理登录、注册、邮箱验证、密码重置请求与密码重置所需的全部组件。你可以随意修改外观与交互唯一不能动的是从wasp/client/auth导入并调用的这五个函数。JavaScript 版本将以下内容保存为src/pages/auth.jsximport { login, requestPasswordReset, resetPassword, signup, verifyEmail, } from wasp/client/auth import { useState } from react import { useNavigate } from react-router-dom // This will be shown when the user wants to log in export function Login() { const [email, setEmail] useState() const [password, setPassword] useState() const [error, setError] useState(null) const navigate useNavigate() async function handleSubmit(event) { event.preventDefault() setError(null) try { await login({ email, password }) navigate(/) } catch (error) { setError(error) } } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / input typepassword value{password} onChange{(e) setPassword(e.target.value)} placeholderPassword / button typesubmitLog In/button /form ) } // This will be shown when the user wants to sign up export function Signup() { const [email, setEmail] useState() const [password, setPassword] useState() const [error, setError] useState(null) const [needsConfirmation, setNeedsConfirmation] useState(false) async function handleSubmit(event) { event.preventDefault() setError(null) try { await signup({ email, password }) setNeedsConfirmation(true) } catch (error) { console.error(Error during signup:, error) setError(error) } } if (needsConfirmation) { return ( p Check your email for the confirmation link. If you dont see it, check spam/junk folder. /p ) } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / input typepassword value{password} onChange{(e) setPassword(e.target.value)} placeholderPassword / button typesubmitSign Up/button /form ) } // This will be shown has clicked on the link in their // email to verify their email address export function EmailVerification() { const [error, setError] useState(null) const navigate useNavigate() async function handleClick() { setError(null) try { // The token is passed as a query parameter const token new URLSearchParams(window.location.search).get(token) if (!token) throw new Error(Token not found in URL) await verifyEmail({ token }) navigate(/) } catch (error) { console.error(Error during email verification:, error) setError(error) } } return ( {error pError: {error.message}/p} button onClick{handleClick}Verify email/button / ) } // This will be shown when the user wants to reset their password export function RequestPasswordReset() { const [email, setEmail] useState() const [error, setError] useState(null) const [needsConfirmation, setNeedsConfirmation] useState(false) async function handleSubmit(event) { event.preventDefault() setError(null) try { await requestPasswordReset({ email }) setNeedsConfirmation(true) } catch (error) { console.error(Error during requesting reset:, error) setError(error) } } if (needsConfirmation) { return ( p Check your email for the confirmation link. If you dont see it, check spam/junk folder. /p ) } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / button typesubmitSend password reset/button /form ) } // This will be shown when the user clicks on the link in their // email to reset their password export function PasswordReset() { const [error, setError] useState(null) const [newPassword, setNewPassword] useState() const navigate useNavigate() async function handleSubmit(event) { event.preventDefault() setError(null) try { // The token is passed as a query parameter const token new URLSearchParams(window.location.search).get(token) if (!token) throw new Error(Token not found in URL) await resetPassword({ token, password: newPassword }) navigate(/) } catch (error) { console.error(Error during password reset:, error) setError(error) } } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typepassword autoCompletenew-password value{newPassword} onChange{(e) setNewPassword(e.target.value)} placeholderNew password / button typesubmitReset password/button /form ) }TypeScript 版本使用 TypeScript 时将上述代码保存为src/pages/auth.tsx并补充事件类型注解与错误类型转换import { login, requestPasswordReset, resetPassword, signup, verifyEmail, } from wasp/client/auth import { useState } from react import { useNavigate } from react-router-dom // This will be shown when the user wants to log in export function Login() { const [email, setEmail] useState() const [password, setPassword] useState() const [error, setError] useStateError | null(null) const navigate useNavigate() async function handleSubmit(event: React.FormEventHTMLFormElement) { event.preventDefault() setError(null) try { await login({ email, password }) navigate(/) } catch (error: unknown) { setError(error as Error) } } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / input typepassword value{password} onChange{(e) setPassword(e.target.value)} placeholderPassword / button typesubmitLog In/button /form ) } // This will be shown when the user wants to sign up export function Signup() { const [email, setEmail] useState() const [password, setPassword] useState() const [error, setError] useStateError | null(null) const [needsConfirmation, setNeedsConfirmation] useState(false) async function handleSubmit(event: React.FormEventHTMLFormElement) { event.preventDefault() setError(null) try { await signup({ email, password }) setNeedsConfirmation(true) } catch (error: unknown) { console.error(Error during signup:, error) setError(error as Error) } } if (needsConfirmation) { return ( p Check your email for the confirmation link. If you dont see it, check spam/junk folder. /p ) } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / input typepassword value{password} onChange{(e) setPassword(e.target.value)} placeholderPassword / button typesubmitSign Up/button /form ) } // This will be shown has clicked on the link in their // email to verify their email address export function EmailVerification() { const [error, setError] useStateError | null(null) const navigate useNavigate() async function handleClick() { setError(null) try { // The token is passed as a query parameter const token new URLSearchParams(window.location.search).get(token) if (!token) throw new Error(Token not found in URL) await verifyEmail({ token }) navigate(/) } catch (error: unknown) { console.error(Error during email verification:, error) setError(error as Error) } } return ( {error pError: {error.message}/p} button onClick{handleClick}Verify email/button / ) } // This will be shown when the user wants to reset their password export function RequestPasswordReset() { const [email, setEmail] useState() const [error, setError] useStateError | null(null) const [needsConfirmation, setNeedsConfirmation] useState(false) async function handleSubmit(event: React.FormEventHTMLFormElement) { event.preventDefault() setError(null) try { await requestPasswordReset({ email }) setNeedsConfirmation(true) } catch (error: unknown) { console.error(Error during requesting reset:, error) setError(error as Error) } } if (needsConfirmation) { return ( p Check your email for the confirmation link. If you dont see it, check spam/junk folder. /p ) } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typeemail value{email} onChange{(e) setEmail(e.target.value)} placeholderEmail / button typesubmitSend password reset/button /form ) } // This will be shown when the user clicks on the link in their // email to reset their password export function PasswordReset() { const [error, setError] useStateError | null(null) const [newPassword, setNewPassword] useState() const navigate useNavigate() async function handleSubmit(event: React.FormEventHTMLFormElement) { event.preventDefault() setError(null) try { // The token is passed as a query parameter const token new URLSearchParams(window.location.search).get(token) if (!token) throw new Error(Token not found in URL) await resetPassword({ token, password: newPassword }) navigate(/) } catch (error: unknown) { console.error(Error during password reset:, error) setError(error as Error) } } return ( form onSubmit{handleSubmit} {error pError: {error.message}/p} input typepassword autoCompletenew-password value{newPassword} onChange{(e) setNewPassword(e.target.value)} placeholderNew password / button typesubmitReset password/button /form ) }挂载到路由以上组件需要与main.wasp.ts中声明的路由对应。参考 email 认证配置文档 中的路由声明方式route(LoginRoute, /login, page(Login, { authRequired: false })) route(SignupRoute, /signup, page(Signup, { authRequired: false })) route(RequestPasswordResetRoute, /request-password-reset, page(RequestPasswordReset, { authRequired: false })) route(PasswordResetRoute, /password-reset, page(PasswordReset, { authRequired: false })) route(EmailVerificationRoute, /email-verification, page(EmailVerification, { authRequired: false }))API 参考wasp/client/auth五个 action 详解以下所有函数均从wasp/client/auth导入。它们的参数契约如下。login()用于登录用户的 action。调用参数data: object必填email: string必填password: string必填成功后务必做重定向例如跳转到应用主页。注意如果用户邮箱尚未验证登录会被拒绝详见下文“登录与注册的内置防护”。signup()用于注册用户并发起邮箱验证的 action。注册成功后用户不会被自动登录因为还需要完成邮箱验证。调用参数data: object必填email: string必填password: string必填:::info 关于额外注册字段 默认情况下Wasp 只会保存email和password两个字段。如果要在注册流程中收集额外字段如用户名、地址等请阅读 自定义注册流程通过auth.methods.email.userSignupFields定义字段提取函数如defineUserSignupFields并在自建注册表单中一并提交这些字段。 :::verifyEmail()用于将邮箱标记为已验证、将用户账户标记为激活的 action。成功后务必做重定向例如跳转到登录页。调用参数data: object必填token: string必填——注册时生成的令牌会以名为token的 URL Query Parameter 形式出现在验证链接中。requestPasswordReset()用于请求发送密码重置邮件的 action。注意它不会立即重置密码只是发送邮件。调用参数data: object必填email: string必填resetPassword()用于确认密码重置并提供新密码的 action。成功后务必做重定向例如跳转到登录页。调用参数data: object必填token: string必填——请求重置时生成的令牌会以名为token的 URL Query Parameter 形式出现在重置链接中。password: string必填——用户的新密码需满足默认密码校验规则。底层实现这些 action 在生成代码中做了什么为了确保自建 UI 的正确用法理解这些客户端 action 的底层实现很有帮助。Wasp 在生成阶段会为每个 action 生成对应的客户端包装代码模板位于waspc/data/Generator/templates/sdk/wasp/auth/email/actions/。例如 login.ts 的实现表明login内部会向 Wasp 生成的登录端点发起POST请求并从响应中取出sessionId随后调用initSession(sessionId)在客户端初始化会话即写入会话状态最后通过handleApiError把后端错误包装为可读异常。因此成功login之后导航到受保护页面是安全的——会话已经就绪。再如 signup.tsexport async function signup(data: EmailSignupData): Promise{ success: boolean } { try { const { success } await api.post({ signupPath }, { json: data, }).json(SuccessResponseSchema); return { success }; } catch (e) { throw handleApiError(e); } }可以看到signup仅向后端提交数据并返回{ success: boolean }不会初始化会话——这印证了文档中“注册后用户不会被登录”的说明。同理verifyEmail.ts 与 passwordReset.ts 中的requestPasswordReset/resetPassword也都是简单的POST 响应校验模式resetPassword同样不会自动建立会话因此成功后要引导用户去登录。当这些函数被调用时它们会抛出经过封装的错误对象含message字段所以自建表单中统一用try/catch捕获并展示error.message即可。token 的来源与传递约定两个需要token的流程邮箱验证、密码重置有一个共同约定邮件中的链接会把token作为 URL 查询参数带到你在main.wasp.ts中为auth.methods.email.emailVerification.clientRoute/auth.methods.email.passwordReset.clientRoute指定的客户端路由上。因此自建页面中需要用以下方式读取const token new URLSearchParams(window.location.search).get(token)拿到token后分别调用verifyEmail({ token })或resetPassword({ token, password })。如果 URL 中没有token示例代码会抛出Token not found in URL错误并显示在页面上——这在用户直接访问验证/重置页面而没有经过邮件链接时会发生属于合理的防御性处理。登录与注册的内置防护自建 UI 同样生效自建 UI 只是替换了前端界面后端行为保持不变。因此以下内置策略依然生效详见 email 认证文档速率限制注册与密码重置请求按邮箱地址限制为每分钟 1 次防止滥用防止邮箱泄露如果有人用已注册且已验证的邮箱再次注册后端会假装注册成功而不是提示“该邮箱已存在”避免泄露邮箱是否被注册允许未验证邮箱重新注册用户用已存在但未验证的邮箱注册时系统允许其重新注册防止恶意用户抢占/锁定他人的邮箱密码校验满足默认密码规则至少 8 位且含数字详见 auth 概述未验证邮箱禁止登录邮箱未验证前登录会被拒绝。自建 UI 中也要相应设计好提示文案——例如注册成功后提示“请查收验证邮件”与后端的“防泄露”策略保持一致避免给出“账号已存在”这类会泄露信息的错误提示。开发调试技巧在开发模式下如果不希望每次注册都走完整的邮件验证流程可以在.env.server中设置SKIP_EMAIL_VERIFICATION_IN_DEVtrue这对日常开发调试以及编写自动化测试非常有用。生产环境中请勿设置此变量。同时为快速验证验证邮件/重置邮件是否发送可在main.wasp.ts中把emailSender.provider配置为Dummy它不会真正发信而是把邮件内容打印到控制台方便你复制邮件中的验证/重置链接进行端到端测试。与预置 Auth UI 的对比与参考Wasp 预置的 Auth UI 组件LoginForm、SignupForm、VerifyEmailForm、ForgotPasswordForm、ResetPasswordForm与自建 UI 是可以混用的——例如自定义注册页、但登录页继续用预置组件。如果你想参考官方 starter 中预置组件的用法可以查看仓库中的waspc/data/Cli/starters/basic/src/auth/email/目录其中 LoginPage.tsx、SignupPage.tsx、EmailVerificationPage.tsx、RequestPasswordResetPage.tsx、PasswordResetPage.tsx 展示了如何用最少的代码把预置表单挂到页面上例如SignupPage通过additionalFields给SignupForm增加自定义字段。对比可见自建 UI 只是把LoginForm替换为你自己的form把底层调用的函数从组件内部搬到你的handleSubmit中——这正是本指南示例代码所做的事情。小结自建邮箱认证 UI 的本质是“界面自绘、动作复用”把login、signup、verifyEmail、requestPasswordReset、resetPassword五个 action 作为与 Wasp 认证后端交互的唯一入口在其上构建任意风格的 React 表单。掌握好每个 action 的参数契约、成功后重定向的时机、token的 URL 传递约定以及后端内置的安全策略你就能在完全自定义视觉体验的同时安全、正确地复刻 Wasp 邮箱认证的全部能力。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
