别再只懂JWT三部分了：手把手教你用Node.js + Express实战JWT登录与权限控制

别再只懂JWT三部分了手把手教你用Node.js Express实战JWT登录与权限控制每次看到技术文章里JWT由Header、Payload、Signature三部分组成的科普我都想问问作者您自己实现过完整的JWT流程吗三年前我第一次在项目中引入JWT时光理解这三部分就花了半小时结果真正落地时却踩了无数坑——密钥该放哪刷新令牌怎么存RBAC权限怎么设计这些问题才是真实开发中的拦路虎。今天我们就用Node.jsExpress搭建一个生产级JWT系统从登录接口到权限控制每个环节都给出可运行的代码。你会看到如何安全地生成带角色信息的JWT令牌中间件如何验证令牌并提取用户信息刷新令牌的存储方案与防篡改设计基于角色的路由权限控制(RBAC)1. 项目初始化与基础配置先创建一个干净的Express项目mkdir jwt-demo cd jwt-demo npm init -y npm install express jsonwebtoken bcryptjs dotenv mongoose在.env中配置关键参数JWT_SECRETyour_strong_secret_here ACCESS_TOKEN_EXPIRES_IN15m # 访问令牌15分钟过期 REFRESH_TOKEN_EXPIRES_IN7d # 刷新令牌7天过期重要安全提示生产环境务必使用更强的密钥推荐至少256位随机字符串且不要将.env文件提交到版本控制基础Express配置// app.js require(dotenv).config() const express require(express) const authRoutes require(./routes/auth) const protectedRoutes require(./routes/protected) const app express() app.use(express.json()) // 路由挂载 app.use(/auth, authRoutes) app.use(/api, protectedRoutes) app.listen(3000, () console.log(Server running on port 3000))2. 用户登录与JWT签发先看用户登录的核心逻辑// controllers/auth.js const jwt require(jsonwebtoken) const bcrypt require(bcryptjs) const login async (req, res) { const { username, password } req.body // 1. 验证用户凭证实际项目需查数据库 const user mockUsers.find(u u.username username) if (!user || !bcrypt.compareSync(password, user.password)) { return res.status(401).json({ error: Invalid credentials }) } // 2. 生成访问令牌 const accessToken jwt.sign( { userId: user.id, role: user.role // 携带角色信息 }, process.env.JWT_SECRET, { expiresIn: process.env.ACCESS_TOKEN_EXPIRES_IN } ) // 3. 生成刷新令牌单独存储 const refreshToken jwt.sign( { userId: user.id }, process.env.JWT_SECRET, { expiresIn: process.env.REFRESH_TOKEN_EXPIRES_IN } ) // 4. 返回双令牌生产环境建议Refresh Token用HttpOnly Cookie res.json({ accessToken, refreshToken, expiresIn: 900 // 前端需要的过期时间秒 }) }关键设计点访问令牌携带role字段用于后续权限控制刷新令牌不包含角色信息降低泄露风险使用bcrypt比较密码哈希值避免明文存储3. JWT验证中间件实现创建可复用的验证中间件// middleware/auth.js const jwt require(jsonwebtoken) const authenticateJWT (req, res, next) { const authHeader req.headers.authorization if (authHeader) { const token authHeader.split( )[1] jwt.verify(token, process.env.JWT_SECRET, (err, user) { if (err) { if (err.name TokenExpiredError) { return res.status(401).json({ error: Token expired }) } return res.sendStatus(403) } req.user user // 将解码后的用户信息挂载到request next() }) } else { res.sendStatus(401) } } module.exports authenticateJWT在受保护路由中使用// routes/protected.js const router require(express).Router() const authenticateJWT require(../middleware/auth) router.get(/dashboard, authenticateJWT, (req, res) { res.json({ message: Welcome ${req.user.userId}, role: req.user.role }) })4. 令牌刷新机制设计刷新令牌需要特殊处理以避免安全漏洞// controllers/auth.js const refreshTokens [] // 生产环境应使用Redis const refresh (req, res) { const { refreshToken } req.body if (!refreshToken || !refreshTokens.includes(refreshToken)) { return res.sendStatus(403) } jwt.verify(refreshToken, process.env.JWT_SECRET, (err, user) { if (err) return res.sendStatus(403) const newAccessToken jwt.sign( { userId: user.userId, role: getRole(user.userId) }, process.env.JWT_SECRET, { expiresIn: process.env.ACCESS_TOKEN_EXPIRES_IN } ) res.json({ accessToken: newAccessToken }) }) }安全增强建议将刷新令牌存入Redis并设置TTL记录设备指纹防止令牌被盗用实现令牌黑名单机制5. 基于角色的权限控制(RBAC)扩展验证中间件实现角色检查// middleware/auth.js const authorize (roles []) { return (req, res, next) { if (!roles.includes(req.user.role)) { return res.status(403).json({ error: Forbidden }) } next() } } // 使用示例 router.get(/admin, authenticateJWT, authorize([admin]), (req, res) { res.json({ message: Admin dashboard }) } )更复杂的权限系统可以在令牌中添加具体权限列表而非角色实现多租户隔离结合数据库动态校验权限6. 前端集成关键要点前端需要处理的主要逻辑// 登录后存储令牌 localStorage.setItem(accessToken, response.data.accessToken) // API请求时携带令牌 axios.interceptors.request.use(config { const token localStorage.getItem(accessToken) if (token) { config.headers.Authorization Bearer ${token} } return config }) // 令牌过期处理 axios.interceptors.response.use( response response, error { if (error.response.status 401) { // 使用refreshToken获取新accessToken return refreshTokenAndRetry(error.config) } return Promise.reject(error) } )7. 生产环境安全加固最后分享几个实战经验密钥管理使用crypto.randomBytes(32).toString(hex)生成强密钥考虑密钥轮换方案令牌存储// 更安全的Cookie设置 res.cookie(refreshToken, refreshToken, { httpOnly: true, secure: true, sameSite: strict })监控与日志记录异常的令牌验证尝试监控令牌刷新频率性能优化对频繁访问的路由实现JWT缓存使用无状态注销方案JWT ID黑名单在最近的一个电商项目中我们通过这套方案实现了日均100万次的认证请求平均延迟控制在15ms以内。最关键的收获是JWT不是简单的三部分拼装而需要根据业务场景设计完整的认证流。