Koa 项目中实现 JWT 用户认证与权限控制

发布时间：2025-05-18 | 分类：项目实战

JWT 简介

JSON Web Token（JWT）是一种开放标准（RFC 7519），用于在各方之间安全地传输信息。在 Koa 项目中，JWT 是实现无状态用户认证的常用方案。

依赖安装

npm install jsonwebtoken koa-jwt

Token 生成与验证工具

const jwt = require('jsonwebtoken');
const SECRET = 'your-secret-key';

// 生成 Token
function generateToken(payload) {
  return jwt.sign(payload, SECRET, { expiresIn: '2h' });
}

// 验证 Token
function verifyToken(token) {
  return jwt.verify(token, SECRET);
}

module.exports = { generateToken, verifyToken };

Koa 中间件集成

const koaJwt = require('koa-jwt');

// 免认证路由
app.use(koaJwt({ secret: SECRET }).unless({
  path: [/^\/api\/login/, /^\/api\/register/]
}));

// 登录接口
router.post('/api/login', async ctx => {
  const { username, password } = ctx.request.body;
  // 验证用户名密码...
  const token = generateToken({ userId: user.id, role: user.role });
  ctx.body = { token };
});

刷新 Token 机制

为避免用户频繁重新登录，可实现双 Token 策略：Access Token（短期）+ Refresh Token（长期）。

// 刷新接口
router.post('/api/refresh', async ctx => {
  const { refreshToken } = ctx.request.body;
  try {
    const payload = verifyToken(refreshToken);
    const newAccessToken = generateToken({ userId: payload.userId });
    ctx.body = { accessToken: newAccessToken };
  } catch (err) {
    ctx.status = 401;
    ctx.body = { error: 'Refresh token expired' };
  }
});

权限控制中间件

function requireRole(role) {
  return async (ctx, next) => {
    if (ctx.state.user.role !== role) {
      ctx.status = 403;
      ctx.body = { error: 'Permission denied' };
      return;
    }
    await next();
  };
}

router.get('/api/admin', requireRole('admin'), async ctx => {
  ctx.body = { data: 'admin data' };
});

总结

JWT 认证在 Koa 中实现简单，配合 koa-jwt 中间件可快速搭建安全的认证体系。生产环境建议使用 HTTPS、设置合理的过期时间，并考虑 Token 黑名单机制用于登出场景。