20 个常见登录失败问题与排查技巧

Henry Wei
发布于 2天前
阅读 95

本章总结 Web3 登录中 20 个常见失败问题，涵盖连接、签名、验签与 JWT 管理，并提供排查建议与用户提示策略。强调前后端一致性、错误码体系与异常处理机制是保障登录系统健壮性的关键。

> 📚 作者：Henry
> 🧱 系列：《[Web2 到 Web3：登录与身份验证机制全面进化](https://learnblockchain.cn/article/17203)》 · 第 7 篇
> 👨‍💻 受众：Web2 & Web3 开发者 / 区块链学习者
> 👉 系列持续更新中，建议收藏专栏或关注作者

## 📋 高频失败问题分类索引（分四大类）

| 类别 | 常见问题数量 |
| --- | --- |
| A. 钱包连接与地址问题 | ①～⑤ |
| B. 签名交互异常 | ⑥～⑩ |
| C. 后端验签失败 | ⑪～⑮ |
| D. 登录态 / Token 问题 | ⑯～⑳ |

---

### ✅ A. 钱包连接与地址问题（前端常见）

| 编号 | 问题描述 | 排查建议 |
| --- | --- | --- |
| ① | 钱包未安装或无法连接 | 使用 `isMetaMaskInstalled()` 检测依赖，并引导安装 |
| ② | 用户拒绝连接钱包 | 捕获错误代码 `4001`，显示非强制提示 |
| ③ | 没有连接任何账户 | `accounts.length === 0`，重新触发 connect 请求 |
| ④ | 网络不匹配 | 判断 `chainId` 是否匹配目标链，调用 `switchNetwork()` |
| ⑤ | 钱包切换账户未同步 | 监听 `accountsChanged` 事件并自动刷新登录状态 |

---

### ✅ B. 签名交互异常（前端签名行为相关）

| 编号 | 问题描述 | 排查建议 |
| --- | --- | --- |
| ⑥ | 用户拒绝签名请求 | 错误代码 `4001`，提示「你取消了登录操作」 |
| ⑦ | 钱包未支持 `signTypedData_v4` | 提示用户升级钱包或回退 `personal_sign` |
| ⑧ | `walletClient` 未初始化 | 使用 `useWalletClient()` 异步检查是否 ready |
| ⑨ | 前端构造的 `TypedData` 错误 | 推荐后端返回结构，避免前端自行构建 |
| ⑩ | 签名值为空或格式异常 | 确保 `signature.length > 130`，非空非全 0x00 |

---

### ✅ C. 后端验签失败（Recover address 不一致）

| 编号 | 问题描述 | 排查建议 |
| --- | --- | --- |
| ⑪ | 签名不符合 TypedData 格式 | 后端校验 `primaryType`, `types`, `domain` 是否一致 |
| ⑫ | `recoverAddress` 返回地址与提交地址不匹配 | 检查域名、Chain ID、Message 内容是否被篡改 |
| ⑬ | 缺少 nonce 或 nonce 重复使用 | 每次登录必须带唯一 nonce，防止重放攻击 |
| ⑭ | 签名被转发伪造 | 使用 `domain.name` 做签名绑定，防钓鱼 |
| ⑮ | 后端未正确配置 `verifyingContract` | 必须与前端使用一致，建议固定于环境变量中配置 |

---

### ✅ D. 登录状态 / JWT 问题

| 编号 | 问题描述 | 排查建议 |
| --- | --- | --- |
| ⑯ | JWT 未返回或丢失 | 检查 `/auth/verify` 返回体，确保正确返回 token |
| ⑰ | token 存储失败 | 检查是否写入 localStorage/Zustand，并在刷新后恢复 |
| ⑱ | token 过期但前端未刷新 | 添加 `exp` 检查逻辑，自动清除并提示 |
| ⑲ | `Authorization` 请求头未带上 token | 封装 `fetchWithAuth()` 工具统一注入 |
| ⑳ | 后端校验失败返回 401 | 检查 token 签发与验证所用密钥一致，解析 token 内容 debug |

---

## 🔧 通用排查思路建议

- ✅ 统一错误捕获中间件（前后端）
- ✅ 提供错误码系统（如 `E-WALLET-001`、`E-JWT-401`）
- ✅ 在前端提供逐步反馈（连接中、签名中、登录中...）
- ✅ 后端打印验签过程日志（地址、payload、signature 片段）
- ✅ 错误提示面向用户：「你未签名」比「4001」更友好

📚 作者：Henry 🧱 系列：《Web2 到 Web3：登录与身份验证机制全面进化》 · 第 7 篇 👨‍💻 受众：Web2 & Web3 开发者 / 区块链学习者 👉 系列持续更新中，建议收藏专栏或关注作者

📋 高频失败问题分类索引（分四大类）

类别	常见问题数量
A. 钱包连接与地址问题	①～⑤
B. 签名交互异常	⑥～⑩
C. 后端验签失败	⑪～⑮
D. 登录态 / Token 问题	⑯～⑳

✅ A. 钱包连接与地址问题（前端常见）

编号	问题描述	排查建议
①	钱包未安装或无法连接	使用 `isMetaMaskInstalled()` 检测依赖，并引导安装
②	用户拒绝连接钱包	捕获错误代码 `4001`，显示非强制提示
③	没有连接任何账户	`accounts.length === 0`，重新触发 connect 请求
④	网络不匹配	判断 `chainId` 是否匹配目标链，调用 `switchNetwork()`
⑤	钱包切换账户未同步	监听 `accountsChanged` 事件并自动刷新登录状态

✅ B. 签名交互异常（前端签名行为相关）

编号	问题描述	排查建议
⑥	用户拒绝签名请求	错误代码 `4001`，提示「你取消了登录操作」
⑦	钱包未支持 `signTypedData_v4`	提示用户升级钱包或回退 `personal_sign`
⑧	`walletClient` 未初始化	使用 `useWalletClient()` 异步检查是否 ready
⑨	前端构造的 `TypedData` 错误	推荐后端返回结构，避免前端自行构建
⑩	签名值为空或格式异常	确保 `signature.length > 130`，非空非全 0x00

✅ C. 后端验签失败（Recover address 不一致）

编号	问题描述	排查建议
⑪	签名不符合 TypedData 格式	后端校验 `primaryType`, `types`, `domain` 是否一致
⑫	`recoverAddress` 返回地址与提交地址不匹配	检查域名、Chain ID、Message 内容是否被篡改
⑬	缺少 nonce 或 nonce 重复使用	每次登录必须带唯一 nonce，防止重放攻击
⑭	签名被转发伪造	使用 `domain.name` 做签名绑定，防钓鱼
⑮	后端未正确配置 `verifyingContract`	必须与前端使用一致，建议固定于环境变量中配置

✅ D. 登录状态 / JWT 问题

编号	问题描述	排查建议
⑯	JWT 未返回或丢失	检查 `/auth/verify` 返回体，确保正确返回 token
⑰	token 存储失败	检查是否写入 localStorage/Zustand，并在刷新后恢复
⑱	token 过期但前端未刷新	添加 `exp` 检查逻辑，自动清除并提示
⑲	`Authorization` 请求头未带上 token	封装 `fetchWithAuth()` 工具统一注入
⑳	后端校验失败返回 401	检查 token 签发与验证所用密钥一致，解析 token 内容 debug