使用 AWS Amplify Auth.signUp 以邮箱和密码注册用户：将 username 复用为邮箱的实战方案

• 文档
• 教程
• 知识库

AWS Amplify 的 Auth 模块支持联合认证（federated）与用户名/密码两种登录方式。本文基于 TIL 仓库中的 aws/sign-up-user-with-email-and-password.md 笔记，讲解一个官方文档语焉不详、但实际开发中极其常见的需求：如何直接用邮箱和密码完成用户注册。读完本文，你将掌握Auth.signUp的正确调用姿势——把邮箱填入username参数、让 Amplify 自动把它注册为该用户的联系邮箱，并能在自己的注册表单中直接落地这套代码。

背景：Amplify Auth 的两种认证形态

AWS Amplify 的 Auth 能力同时提供两种认证路径：

• 联合认证（Federated）：通过 Google、Facebook、Apple 等第三方身份提供商完成登录，适合免密码的社交登录场景；
• 用户名/密码认证（Username/Password）：由应用自己收集用户凭证并提交给 AWS Cognito 用户池，适合传统邮箱注册、企业后台账号等场景。

对于绝大多数 Web 应用来说，邮箱 + 密码是最主流的注册形态。问题在于：Amplify 官方文档并没有把「用邮箱注册」的写法讲透，初次接触的开发者很容易在signUp的参数上卡住。这篇 TIL 笔记记录的正是这个关键点：signUpAPI 要求传入一个必需的username参数，而它完全可以直接塞入用户填写的邮箱地址。

核心技巧：username 参数就是邮箱

从 aws/sign-up-user-with-email-and-password.md 可以看到，Auth.signUp的调用签名中最容易让人困惑的正是username。直觉上我们会为「用户名」和「邮箱」分别准备两个字段，但 Amplify 的设计允许你只用一个字段：

import { Auth } from 'aws-amplify'; async function signUp({ email, password }) { try { const user = await Auth.signUp({ username: email, password, attributes: {}, }); console.log({ user }); } catch (error) { console.log('error signing up:', error); } }

这段代码揭示了两个要点：

1. username: email——把用户输入的邮箱字符串直接赋给username参数，Amplify 会识别出这是一个邮箱格式的值，而不是要求你单独提供显示用用户名；
2. attributes: {}——在这里可以附带额外的用户属性（如name、phone_number等自定义字段），本例无需额外属性，因此传入空对象。

与注册表单的完整对接

笔记中的signUp函数以解构的方式接收{ email, password }，这正对应了注册表单的典型形态。当用户填写完注册表单并点击提交后，把表单值原样传入即可：

// 表单提交处理函数（示意） async function handleSubmit(formValues) { const { email, password } = formValues; await signUp({ email, password }); }

关键行为可以概括为：email作为username传入，password原样透传。也就是说，这个函数本质上只做了两件事——把邮箱搬到username的位置，把密码交给password字段，剩下的认证注册逻辑全部由 Amplify 处理。

对于异步错误处理，try/catch结构覆盖了常见的失败场景（如邮箱已被注册、密码不符合用户池策略、网络异常等），错误信息会通过console.log('error signing up:', error)打印，方便开发阶段定位问题。生产环境可以将这段逻辑改为向 UI 层返回结构化错误，再展示给用户。

注册之后：邮箱如何被 Amplify 处理

这是本篇笔记最有价值的结论。当signUp成功调用后：

• Amplify Auth 会将username解释为邮箱，并把该邮箱注册为这个用户的联系邮箱（contact email）；
• 用户在 Cognito 用户池中的登录标识即是这个邮箱，后续Auth.signIn登录时也可以直接使用邮箱作为登录凭证；
• 该邮箱也会被用于后续的账号验证流程（例如邮箱确认码的发送目标地址）。

这意味着你无需在attributes里重复声明邮箱，也不用担心两处邮箱不一致的问题——一个username参数同时承担了「登录标识」和「联系邮箱」两个职责，减少了一处容易出错的重复输入。

在 TIL 仓库中的定位与相关阅读

本仓库（README 见 README.md）是一个 Today I Learned 式的技术笔记集合，AWS 类别下收录了多篇与 AWS 开发相关的实操笔记，本文对应条目为 Sign Up User With Email And Password 中的 aws/sign-up-user-with-email-and-password.md。

如果你正在搭建完整的 AWS 前端开发环境，还可以参考同一目录下的 use-specific-aws-profile-with-cli.md，它介绍了如何通过--profile参数或AWS_PROFILE环境变量在多套 AWS 凭证之间切换——当 Amplify 项目需要关联到指定 AWS 账号的 Cognito 用户池时，这类 CLI 配置知识同样不可或缺。

小结

• 注册用户只需要调用Auth.signUp，把表单里的邮箱填入username、密码原样传给password即可；
• Amplify 会自动把该值识别为邮箱，并登记为用户的联系邮箱，同时它也是后续登录的凭证；
• 官方文档对这一点交代不清，本文的写法经过 aws/sign-up-user-with-email-and-password.md 笔记验证，可直接复制到项目中使用。

• 文档
• 教程
• 知识库