AWS Amplify 中解决 OTP 验证失败问题的技术指南

问题背景

在使用 AWS Amplify 构建无密码登录功能时，开发者可能会遇到一个常见问题：在尝试通过电子邮件 OTP（一次性密码）验证用户身份时，系统抛出错误提示"Auth UserPool not configured"。这个错误通常发生在开发者按照官方文档配置了 Cognito 用户池以支持无密码登录方式后。

错误现象

当用户输入电子邮件地址并请求发送验证码后，系统能够正确发送包含 OTP 的电子邮件。然而，当用户输入收到的验证码并提交时，前端控制台会显示以下错误信息：

OTP verification failed: AuthUserPoolException: Auth UserPool not configured.

根本原因分析

经过深入排查，发现这个问题的主要原因是项目中存在多个版本的 Amplify 核心库。具体表现为：

1. 项目中同时安装了 aws-amplify 和 @aws-amplify/auth 两个包
2. 这两个包都依赖 @aws-amplify/core，导致应用中创建了多个核心库实例
3. 这种重复实例化破坏了 Amplify 的单例模式设计，导致身份验证流程无法正确完成

解决方案

解决这个问题的步骤非常简单：

1. 从项目的 package.json 文件中移除 @aws-amplify/auth 依赖
2. 仅保留 aws-amplify 作为身份验证相关的依赖
3. 重新安装依赖并构建项目

技术细节

AWS Amplify 的设计采用了单例模式来管理身份验证相关的配置和状态。当项目中存在多个核心库实例时：

• 配置信息可能无法正确共享
• 身份验证状态管理会出现混乱
• 令牌存储和验证流程可能中断

aws-amplify 包已经包含了 @aws-amplify/auth 的所有功能，因此不需要单独安装后者。这种模块化设计旨在简化依赖管理，但如果不注意可能会引入重复依赖的问题。

最佳实践

为了避免类似问题，建议开发者：

1. 定期检查项目依赖关系，避免重复安装功能重叠的包
2. 使用 npm ls 或 yarn why 命令分析依赖树
3. 遵循官方文档中的依赖推荐配置
4. 在升级 Amplify 版本时，注意检查废弃的包和替代方案

总结

AWS Amplify 提供了强大的身份验证功能，包括无密码登录等现代认证方式。通过正确管理项目依赖，开发者可以充分利用这些功能而不会遇到配置问题。记住，在大多数情况下，仅需要安装 aws-amplify 元包即可获得完整的身份验证功能集。

这个问题的解决不仅修复了 OTP 验证流程，也为项目建立了更健康的依赖关系基础，有利于长期维护和功能扩展。