扫码登录实现原理与源码详解：从零构建你的扫码认证系统

最近在技术圈里看到不少朋友在询问“扫码登录”的源码实现。确实，随着移动互联网的普及，扫码登录已经成为了Web应用标配的功能之一。不管是微信、GitHub还是各类SaaS平台，大家都在用。

扫码登录涉及PC端、手机端和服务端三个核心角色，通过二维码作为中介完成身份认证。

但很多开发者只见过“扫码”这步动作，对背后到底发生了什么其实是一知半解。今天，我们就把这件事揉碎了讲一讲，顺便聊聊怎么从零开始撸一个简单的扫码登录系统。

一、 扫码登录的核心逻辑是什么？

扫码登录本质上是一种“跨端认证”的机制。它的核心目的只有一个：让笨重的PC端，借道移动端便捷的身份体系来完成登录。

简单来说，整个流程可以分为三个核心角色：

1. PC端（浏览器）：用来显示二维码，监听登录状态。
2. 手机端（App/扫码器）：用来确认身份，告知服务器“这人是我”。
3. 服务端：作为中间人，协调PC端和手机端的信息同步。

二、 标准实现流程拆解

市面上绝大多数扫码登录，虽然细节不同，但大体逻辑是一致的。我们可以把它总结为“三步走”策略。

第一步：PC端发起请求，获取“凭证”

当用户打开PC网站的登录页时，页面会向后端发起一个请求，请求一个唯一的“二维码ID”（我们可以叫它 uuid 或 token）。

• 后端动作：生成一个全局唯一的字符串（UUID），将这个字符串存入Redis或内存中，标记状态为“待扫描”（WAITING），并设置一个过期时间（比如2分钟防止刷票）。
• 前端动作：拿到这个UUID后，利用前端库（如 qrcode.js）将其绘制成二维码展示给用户。

第二步：手机扫码，确认身份

PC端获取登录状态主要有轮询和WebSocket长连接两种方式，前者实现简单但效率低，后者实时性好但实现复杂。

用户掏出手机，扫这个二维码。

这里有一个关键点：二维码里包含的信息并不是用户的密码，仅仅是第一步生成的那个 UUID。手机扫码后，解析出UUID，然后连同手机端的登录凭证（比如Cookie、Token或用户输入的账号密码）一起发送给服务端。

• 后端动作：
  1. 校验手机端发来的身份是否合法。
  2. 如果合法，将数据库/Redis中该UUID的状态更新为“已确认”（CONFIRMED），并绑定对应的用户ID。

第三步：PC端获知结果，完成登录

这是最容易卡住新手的地方：PC端怎么知道用户在手机上点“确认”了？主要有两种方案。

方案A：轮询—— 最简单也最笨

PC端每隔一秒钟发一次请求给后端：“喂，UUID为xxx的二维码状态变了吗？”

• 优点：实现极其简单，几乎所有环境都支持。
• 缺点：延迟高（最坏情况1秒延迟），无效请求多，服务器压力大。

方案B：WebSocket长连接 —— 现代标准做法

PC端与后端建立WebSocket连接。后端一旦收到手机端的确认指令，直接通过WebSocket推送消息给PC端。

• 优点：实时性极高，体验丝滑，无多余请求。
• 缺点：实现稍微复杂一点，需要处理连接断开重连等逻辑。

三、 纯干货：简易实现参考

既然大家要“源码”，这里我就给一个核心逻辑的伪代码实现，你可以根据自己熟悉的语言（Node.js, Python, Go, Java等）进行翻译。

1. 模拟后端核心逻辑 (以伪代码为例)

// 假设我们使用一个全局对象存储二维码状态（生产环境请用Redis）
const qrStore = {};

// 1. PC端请求获取二维码ID
function getQrCode() {
    const uuid = generateUUID();
    qrStore[uuid] = { status: 'WAITING', userId: null };
    return { success: true, uuid: uuid };
}

// 2. 手机端扫码确认
function confirmLogin(uuid, userToken) {
    // 校验userToken是否有效，获取userId
    const userId = validateUserToken(userToken);

if (qrStore[uuid] && userId) {
        qrStore[uuid].status = 'CONFIRMED';
        qrStore[uuid].userId = userId;
        // 触发WebSocket推送逻辑（在此处省略）
        return { success: true };
    }
    return { success: false, msg: '二维码无效或已过期' };
}

// 3. PC端轮询检查状态（如果是WebSocket则此处不需要）
function checkStatus(uuid) {
    if (!qrStore[uuid]) return { status: 'EXPIRED' };

if (qrStore[uuid].status === 'CONFIRMED') {
        // 生成PC端的登录凭证
        const pcToken = generatePCToken(qrStore[uuid].userId);
        return { status: 'SUCCESS', token: pcToken };
    }

return { status: 'WAITING' };
}

2. 前端轮询逻辑示例

let pollTimer = null;

function startPolling(uuid) {
    pollTimer = setInterval(async () => {
        const res = await fetch(`/api/login/status?uuid=${uuid}`);
        const data = await res.json();

if (data.status === 'SUCCESS') {
            clearInterval(pollTimer);
            alert('登录成功！Token: ' + data.token);
            // 跳转到主页
            window.location.href = '/dashboard';
        } else if (data.status === 'EXPIRED') {
            clearInterval(pollTimer);
            alert('二维码已过期，请刷新重试');
        }
    }, 1000); // 每秒查询一次
}

四、 避坑指南与进阶建议

如果你打算在生产环境中使用，光有上面那段代码是不够的，这里有几个必须注意的细节：

1. 安全性：二维码的UUID必须具备随机性和不可预测性，防止被恶意遍历猜测。此外，确认登录的接口必须校验手机端的高权限Token。
2. 防止重复消费：一个二维码只能用一次。一旦登录成功或过期，服务端必须立即销毁或标记该UUID，防止被重复利用。
3. WebSocket心跳：如果采用WebSocket方案，别忘了处理PC端页面关闭后的断连清理，否则服务器会残留大量无用的连接句柄，导致内存泄漏。
4. 并发控制：如果是高并发场景，Redis的读写性能是关键，建议单独使用一个DB实例来存中间态数据。

五、 总结

扫码登录听起来高大上，其实拆解开来就是：生成ID -> 轮询/监听 -> 状态变更 -> 下发凭证 这一套组合拳。

希望这篇拆解能帮你理清思路。如果你在具体实现中遇到问题（比如WebSocket握手失败、Token存储设计等），欢迎在评论区讨论，我们可以继续深挖对应的细节。