email-and-password-best-practices

email-and-password-best-practices 技能概览

email-and-password-best-practices 是一份聚焦 Better Auth 的配置指南，适合需要落地传统账号密码登录的团队，重点补齐常被忽略的安全环节：邮箱验证、密码重置、密码策略以及密码哈希配置。它尤其适合已经确定要使用 Better Auth、希望尽快把 email/password 流程正确上线的开发者，而不是还在看泛泛的认证入门说明。

这个技能能帮你完成什么

当你的真实目标是把一套可上线、足够安全的 email/password 流程接好时，就该用这个技能：

• 启用 Better Auth 的 email/password 登录
• 发送验证邮件
• 在需要时要求完成邮箱验证后才能登录
• 增加 reset-password 邮件发送能力
• 应用密码规则与校验
• 调整哈希行为
• 执行必须的 migration 步骤

什么人适合安装这个技能

这个技能特别适合：

• 在 Better Auth 项目里增加用户名/邮箱登录的应用团队
• 想把零散、临时的认证实现替换成可重复配置路径的开发者
• 使用 AI 辅助编码，希望 agent 能记住 Better Auth 特定配置项名称和配置顺序的工作流

如果你还在不同 auth provider 之间做选型，或者你的应用只用 OAuth / passkeys、完全不需要密码，那它的价值就没那么大。

为什么它比通用 auth 提示词更好用

通用提示词可能只会让 agent “加上登录和重置密码”。而这个技能会把需求收束成 Better Auth 里真正需要动的配置项和实际顺序，包括 emailAndPassword: { enabled: true }、emailVerification.sendVerificationEmail、reset-password 处理，以及 npx @better-auth/cli@latest migrate。这会让 用于 Access Control 的 email-and-password-best-practices 场景可靠得多。

在决定采用前，最值得先确认的事

安装前，先看这些决策点是否明确：

• 你必须已经有可用的邮件发送函数，或至少有明确计划
• 你需要决定登录时是否必须要求邮箱已验证
• 你最好已经想清楚密码策略要求
• 你需要有权限执行 Better Auth migrations
• 你应该能修改 auth server 配置，而不只是前端表单

如何使用 email-and-password-best-practices 技能

email-and-password-best-practices 技能的安装方式

从 Better Auth skills 仓库安装这个技能：

npx skills add https://github.com/better-auth/skills --skill emailAndPassword

之后，在需要配置、审查或改进 Better Auth 凭证登录流程的 AI 编码会话里调用它。

先读这个文件

从这里开始：

• better-auth/emailAndPassword/SKILL.md

这个仓库切片本身很轻量，所以重点不在于翻大量配套文件，而在于把里面的指导准确落到你的代码库里。

这个技能需要你提供哪些输入

你需要把仓库本身无法推断的上下文明确告诉 agent：

• 你的 Better Auth 配置文件路径
• email/password 是否已经部分启用
• 你使用的邮件发送 provider 或 helper function
• 邮箱验证是可选还是强制
• 你希望的 reset-password 用户流程
• 是否有密码长度或复杂度要求
• 是否需要自定义 hashing 设置

如果没有这些上下文，agent 依然可以帮你搭一个框架，但产出通常会比较泛。

如何把模糊目标变成高质量提示词

弱提示词：

• “Set up auth with Better Auth.”

更好的提示词：

• “Use the email-and-password-best-practices skill to configure Better Auth email/password login in src/lib/auth.ts, require email verification before sign-in, add sendVerificationEmail using our existing sendEmail() helper, implement reset-password email sending, and tell me what migration command and test steps I need.”

之所以更有效，是因为它一次性给了文件位置、是否强制验证、现有发信能力，以及预期交付内容。

推荐的配置工作流

一个实用的顺序是：

1. 在 Better Auth 中启用 email/password。
2. 加上验证邮件发送。
3. 决定登录前是否必须完成邮箱验证。
4. 加上 reset-password 邮件发送。
5. 应用密码校验规则。
6. 只有在确实有理由时再检查 hashing 设置是否要自定义。
7. 运行 migration。
8. 端到端测试注册、验证、登录和重置流程。

这个顺序可以减少返工，也符合大多数团队实际排查 auth 上线问题的节奏。

这个技能围绕的核心配置

这个技能主要围绕以下 Better Auth 功能展开：

• emailAndPassword: { enabled: true }
• emailVerification.sendVerificationEmail
• emailAndPassword.requireEmailVerification
• sendResetPassword
• 密码策略配置
• 哈希算法自定义
• npx @better-auth/cli@latest migrate

如果你的提示词没有说明其中哪些是你真正需要的，agent 很可能会替你选择一些你本来不想要的默认值。

邮箱验证通常才是采用时的最大阻碍

对大多数团队来说，难点不在于“打开密码登录”，而在于把邮箱验证这件事安全地交付上线。这个技能的价值之一，是它会提醒 agent：sendVerificationEmail 接收的是 { user, url, token }，而且传入的 url 已经包含验证链接。这样就能避免明明已有完整 URL，却又错误地自己重建链接。

什么时候应该强制已验证邮箱才能登录

如果你的访问控制模型要求用户在使用账户前先确认身份，就应该启用 emailAndPassword.requireEmailVerification。仓库里的说明还提到一个很关键的行为：未验证用户尝试登录时，会收到一封新的验证邮件。这类运行时细节，很多通用提示词都不会提醒你。

关于密码重置的使用建议

如果你的应用支持“忘记密码”找回，最好明确要求 agent 接入 sendResetPassword，并展示完整用户旅程：

• 发起重置请求
• 收到邮件
• 点击链接
• 设置新密码
• 再次登录

不要只说“做一个 reset password backend”，否则最后很可能只得到一个没有投递步骤的半成品。

密码策略与前端校验

这个技能会覆盖密码策略，但如果你提前说清这些点，结果会更好：

• 最小长度
• 是否要求特殊字符
• 前端校验是否要与后端规则完全一致
• 是否需要返回用户友好的校验提示

如果你的团队希望注册、修改密码和重置密码时行为一致，这一点尤其重要。

哈希自定义并不总是必需的

email-and-password-best-practices 的使用路径包含 hashing 自定义，但这更适合进阶场景。除非你有合规、迁移或性能方面的明确原因，否则更推荐让 agent 保留安全默认值，并解释这些默认值，而不是没必要地改算法。

实现后的实用测试清单

可以让 agent 验证以下场景：

• 新用户注册成功
• 验证邮件成功发送
• 验证链接可正常使用
• 如果要求验证，未验证用户登录会被拦截
• 在预期情况下，重复登录会触发重新发送验证邮件
• reset-password 邮件发送成功
• 重置后旧密码失效
• 弱密码输入时，系统能清晰地返回校验失败信息

这正是 email-and-password-best-practices 指南 比简单扫一眼仓库更有价值的地方：它帮助你测试的是实际行为，而不只是把配置贴上去。

email-and-password-best-practices 技能常见问题

这个技能只适用于 Better Auth 吗？

是的。这是一个针对 Better Auth 配置与流程的 provider-specific 技能。如果你不用 Better Auth，这些配置名和 migration 步骤都不能直接照搬。

email-and-password-best-practices 技能对新手友好吗？

大体上友好，前提是你已经知道 auth 配置放在哪里，以及应用是怎么发邮件的。完全零基础的用户，通常还需要额外补上 SMTP、事务邮件 provider、路由接线和前端表单方面的帮助。

它会自己安装任何东西吗？

不会。这个技能本质上是面向 AI 工作流的指导。你的项目仍然需要先接好 Better Auth、你依赖的邮件 provider 集成，以及在你的环境里实际执行 migration 命令。

什么情况下不该使用这个技能？

以下情况建议跳过：

• 你只需要 OAuth 或 passkeys
• 你正在比较不同认证平台，而不是实际实现 Better Auth
• 你的应用明确禁止密码登录
• 你需要的是更宽泛的安全架构评审，而不是 Better Auth 配置任务

它和直接让 LLM 帮我做 auth，有什么不同？

email-and-password-best-practices 技能更聚焦，也更可执行。它会把模型引导到 Better Auth 真实的配置面，以及邮箱验证和重置流程相关的运行细节上，从而减少凭空编造 API 和漏步骤的情况。

它对用于 Access Control 的 email-and-password-best-practices 有帮助吗？

有，尤其是在你的访问控制依赖“先验证身份、再开放应用访问”的情况下。是否拦截未验证用户登录，是这个技能最重要、也最容易做错的策略决策之一。

如何改进 email-and-password-best-practices 技能的使用效果

直接告诉技能你的 auth 文件和邮件 helper

想最快提升输出质量，最有效的方法就是把正确文件和现有邮件工具明确指给 agent。比如：

• “Edit src/lib/auth.ts and use lib/email/sendEmail.ts.”

这样可以减少猜测，也能避免 agent 凭空造抽象层。

提前明确你的验证策略

在处理 email-and-password-best-practices 时，少一句话，往往就会多很多返工：

• “Users must verify email before first sign-in.”

或者：

• “Users can sign in before verification, but we still send verification email.”

如果你不说明这点，最后做出来的实现可能“安全上没问题”，但并不符合你的产品要求。

不要只要配置，要求输出端到端流程

更强的请求方式是：

• “Configure the backend and show the frontend/user flow, email triggers, migration command, and manual test plan.”

这样可以避免一种常见的不完整输出：auth server 配好了，但没人知道用户该怎么真正走完整个流程。

留意这些常见失败模式

使用这个技能时，常见问题包括：

• 忘了实现实际的邮件投递
• 明明 url 已经提供了，却还自己生成验证链接
• 开启了验证，却没有决定登录时是否必须拦截未验证用户
• 接好了 reset-password 的发送链路，却没有测试回调路径
• 前端加了密码规则，但和后端校验不一致

想把密码处理做好，就把策略细节说具体

如果你的环境对密码强度有要求，请给出明确规则。“Use strong passwords” 太空泛了。更好的提示词会写清楚长度、禁用模式、重置要求，以及是要求存量用户立刻遵守，还是只在修改/重置密码时生效。

让 agent 解释取舍，而不只是改代码

可以额外加一句：

• “Explain why you kept defaults or changed hashing settings, and note any security/usability tradeoffs.”

这样更便于评审，也能帮助团队避免照着“安全最佳实践”生搬硬套，结果做出不必要的改动。

第一版完成后，再带着失败场景迭代一次

在 agent 给出初版实现后，可以继续追问：

• “Now review this for unverified-user edge cases.”
• “Add manual test cases for expired reset links.”
• “Check whether password validation is consistent between sign-up and reset.”

很多时候，正是第二轮迭代，才真正体现出安装 email-and-password-best-practices 的价值：它能让后续优化始终建立在 Better Auth 的真实行为之上，而不是滑向泛泛而谈的 auth 建议。