手把手教你用Node.js实现微信小程序扫一扫登录（含完整代码）

最新推荐文章于 2026-05-15 06:55:32 发布

原创

最新推荐文章于 2026-05-15 06:55:32 发布 · 441 阅读

标签

#Node.js #微信小程序 #扫码登录 #Web开发

手把手构建基于Node.js的微信小程序扫码登录系统：从原理到实战部署

最近在重构一个内部工具平台时，遇到了一个很实际的需求：如何让用户在电脑端用微信扫码就能快速登录，而无需记忆复杂的账号密码。市面上成熟的第三方登录方案虽然方便，但要么有调用限制，要么数据掌控力不足。经过一番技术选型，最终决定基于微信小程序的能力，自己搭建一套扫码登录系统。今天就把这套从零到一、经过生产环境验证的方案完整分享出来，不仅包含可运行的代码，更重要的是背后的设计思路和那些官方文档里不会写的“坑点”。

这套方案的核心逻辑其实很清晰：用户在电脑浏览器打开登录页，页面展示一个动态生成的二维码；用户用微信扫描这个二维码，如果已经授权过我们的小程序，就会自动完成登录；如果尚未授权，则会在小程序内弹出授权窗口，用户确认后，登录成功，电脑页面自动跳转。整个过程流畅自然，用户体验接近主流互联网产品。下面，我们就从环境准备开始，一步步拆解每个环节。

1. 前期准备与环境配置

在动手写代码之前，有几个关键的“基础设施”需要提前搭建好。这就像盖房子前要打地基，地基稳了，后面的开发才能顺风顺水。

首先，你需要一个已经完成企业认证的微信小程序。个人主体的小程序无法获取用户的unionId，而unionId是打通同一用户在不同应用（公众号、小程序、开放平台）身份的唯一标识，对于后续可能的业务扩展至关重要。在微信公众平台注册并认证后，记下你的AppID和AppSecret，这是后续所有API调用的通行证。

注意：AppSecret是极其敏感的信息，相当于小程序的密码，绝对不要直接硬编码在客户端代码或提交到公开的代码仓库。务必通过环境变量或安全的配置中心来管理。

我们的技术栈以Node.js为核心，这里以Koa框架为例，因为它轻量、优雅，中间件机制非常适合组织扫码登录的流程。你需要确保本地环境已安装Node.js（建议版本14以上）和npm。

创建一个新的项目目录，并初始化依赖：

mkdir wechat-scan-login && cd wechat-scan-login
npm init -y

接着，安装核心依赖包：

npm install koa koa-router koa-static axios ws

koa, koa-router: 用于构建Web服务器和路由。
koa-static: 用于托管静态文件（如登录页面）。
axios: 用于向微信服务器发起HTTP请求。
ws: 一个简单好用的WebSocket库，用于实现浏览器与服务器的实时通信，这是通知登录成功的关键。

此外，我们还需要一个持久化存储来管理登录状态和临时票据。在生产环境中，Redis是最佳选择，因为它性能高，且支持设置自动过期时间，完美契合扫码登录这种“临时-验证”的场景。这里为了演示完整流程，我们会先用一个内存对象模拟，但会明确指出在生产环境中应如何替换为Redis。

2. 核心架构设计与通信流程剖析

在开始写具体代码前，我们必须把整个系统的数据流和组件交互想清楚。一张清晰的蓝图能避免后期陷入“拆东墙补西墙”的混乱。整个扫码登录体系涉及三个角色：电脑浏览器、我们的Node.js服务器和微信小程序（运行在用户手机微信内）。

它们的交互时序可以用以下步骤来描述：

生成登录场景：用户访问电脑上的登录页，浏览器向我们的Node服务器发起请求，请求一个“登录场景ID”。
获取并展示二维码：Node服务器收到请求后，向微信服务器申请一个带有该“场景ID”的小程序码，并将图片返回给浏览器展示。
用户扫码：用户用微信扫描小程序码，微信会识别并跳转到我们指定的小程序页面，同时将“场景ID”带给小程序。
小程序端授权与上报：小程序获取用户授权（如已授权则静默获取），拿到用户的openId和unionId，然后调用Node服务器的一个接口，上报“用户身份”与“场景ID”的绑定关系。
实时通知登录成功：Node服务器收到上报后，通过WebSocket找到正在等待这个“场景ID”的浏览器连接，推送“登录成功”的消息。
页面跳转与凭证下发：浏览器收到消息，跳转到登录后页面，Node服务器同时生成自定义登录态（如Session或Token）返回给浏览器。

这里最关键的两个技术点是：小程序码的生成和WebSocket长连接。小程序码是承载“场景ID”的载体，而WebSocket则是连接“手机端操作”与“电脑端响应”的桥梁，避免了低效的轮询。

为了更清晰地管理整个流程中的状态，我们在服务器端需要维护几个核心数据：

数据键名	存储内容	过期时间	作用
`scan:scene:[sceneId]`	`{ status: ‘waiting’, userId: null, wsConn: [连接对象] }`	300秒	记录每个扫码场景的状态和对应的WebSocket连接。
`user:session:[token]`	`{ userId, openId, unionId }`	7天	用户登录成功后颁发的持久化会话。
`wx:access_token`	微信接口调用凭证	通常7200秒	缓存从微信获取的`access_token`，避免频繁请求。

3. 后端核心模块实现

理论清晰后，我们开始动手实现Node.js后端。我们将代码模块化，分为服务器入口、微信服务模块、WebSocket服务和路由控制器。

首先，创建微信服务模块 (wechat-service.js)。这个模块封装所有与微信服务器交互的逻辑，是系统的中枢。

const axios = require(‘axios’);
const fs = require(‘fs’);
const path = require(‘path’);

class WeChatService {
  constructor(appId, appSecret) {
    this.appId = appId;
    this.appSecret = appSecret;
    this.accessToken = null;
    this.tokenExpireTime = 0;
    // 生产环境应替换为Red