JavaScript JWT 库深度对比：jose vs jsonwebtoken vs node-jose

在 JavaScript 生态中处理身份验证和数据交换时，JSON Web Token (JWT) 是核心标准。然而，围绕 JWT 的库众多，从高层封装到底层原语各不相同。jose、jsonwebtoken、node-jose 提供了不同层次的抽象，而 jws 和 jwa 则关注更底层的签名和算法。本文将深入对比这些库的技术细节，帮助你在架构决策中做出正确选择。

🚀 核心用法：签名与验证

jose 提供了现代化的 Promise 基于 API，支持 ESM 和 CJS。

• 使用 SignJWT 类进行链式调用。
• 验证使用 jwtVerify 函数。
• 默认行为更安全，防止算法混淆攻击。

// jose: 签名
import { SignJWT } from 'jose';
const jwt = await new SignJWT({ 'urn:example:claim': true })
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .sign(secret);

// jose: 验证
import { jwtVerify } from 'jose';
const { payload } = await jwtVerify(jwt, secret);

jsonwebtoken 是经典的回调风格 API，也支持 Promise。

• API 简单直观，适合快速开发。
• 在 Node.js 后端非常普及。
• 需要注意配置选项以防止安全漏洞。

// jsonwebtoken: 签名
const jwt = require('jsonwebtoken');
const token = jwt.sign({ foo: 'bar' }, secret, { algorithm: 'HS256' });

// jsonwebtoken: 验证
const decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });

node-jose 提供了基于 Promise 的 API，但风格较旧。

• 支持 JWS 和 JWE 标准。
• 代码结构相对繁琐，不如 jose 简洁。
• 适用于需要特定 JWS 格式兼容的场景。

// node-jose: 签名
const jose = require('node-jose');
const signature = await jose.JWS.createSign({ format: 'compact' }, key)
  .update(JSON.stringify(payload))
  .final();

// node-jose: 验证
const verified = await jose.JWS.createVerify(key)
  .verify(signature);

jws 专注于 JSON Web Signature 底层实现。

• 不处理 JWT claims（如 exp, iat），只处理签名本身。
• 适合需要自定义负载结构的场景。

// jws: 签名
const jws = require('jws');
const token = jws.sign({
  header: { alg: 'HS256' },
  payload: { foo: 'bar' },
  secret: 'shhhhh'
});

jwa 处理底层算法逻辑。

• 用于创建签名实例或验证算法支持。
• 通常不直接用于生成 JWT，而是作为构建块。

// jwa: 算法实例
const jwa = require('jwa');
const hmac = jwa('HS256');
const sig = hmac.sign('data', 'secret');

🌍 运行环境：Node.js 与浏览器

jose 是为同构环境设计的。

• 在 Node.js 中使用 Crypto 模块。
• 在浏览器中使用 Web Crypto API。
• 无需配置打包工具即可在两端运行。

// jose: 浏览器环境同样适用
// 无需更改代码，自动检测环境
import { generateKeyPair } from 'jose';
const { publicKey, privateKey } = await generateKeyPair('RS256');

jsonwebtoken 主要针对 Node.js 服务器。

• 依赖 Node.js 的 crypto 模块。
• 在浏览器中无法直接使用，需要 polyfill 或替代方案。
• 适合纯后端服务。

// jsonwebtoken: 仅限 Node.js
// 在浏览器中运行会报错，因为依赖 process.env 和 node crypto
const jwt = require('jsonwebtoken'); 

node-jose 支持 Node.js 和部分浏览器环境。

• 通过 shim 支持浏览器，但配置较复杂。
• 体积较大，不如 jose 轻量。

// node-jose: 浏览器需要额外配置
// 通常不建议在现代前端架构中使用

jws 和 jwa 是 Node.js 优先的底层库。

• 主要设计用于服务器端签名逻辑。
• 浏览器支持有限，需自行处理兼容性问题。

// jws/jwa: 主要在 Node.js 环境使用
// 浏览器端使用需谨慎

🔒 安全性与算法支持

jose 默认禁止不安全算法。

• 不支持 none 算法，防止签名绕过。
• 明确指定允许的算法列表，减少配置错误。
• actively 维护，修复漏洞迅速。

// jose: 强制指定算法
// 如果不指定，默认安全配置生效
await jwtVerify(jwt, key, { algorithms: ['RS256'] });

jsonwebtoken 历史上存在算法混淆风险。

• 早期版本允许攻击者更改算法为 none。
• 现在需要显式指定 algorithms 选项以确保安全。
• 社区庞大，安全审计较多。

// jsonwebtoken: 必须显式指定算法
jwt.verify(token, key, { algorithms: ['RS256'] }); 

node-jose 支持广泛的 JWS/JWE 算法。

• 适合需要复杂加密场景（如 JWE 加密负载）。
• 配置不当可能导致安全风险。

// node-jose: 支持 JWE
const encrypted = await jose.JWE.createEncrypt({ format: 'compact' }, key)
  .update(JSON.stringify(payload))
  .final();

jws 和 jwa 提供原始能力。

• 不阻止不安全算法，开发者需自行负责。
• 适合构建自定义安全协议，而非直接使用。

// jws: 不验证算法安全性
// 开发者需确保 header 中的 alg 是可信的

📊 总结对比表

💡 最终建议

jose 是目前最稳健的选择 🛡️。它解决了 jsonwebtoken 在浏览器端不可用的问题，同时提供了更安全的默认配置。如果你的项目需要前端验证令牌，或者你希望采用现代 ESM 模块标准，jose 是唯一推荐。

jsonwebtoken 依然有价值 📦。对于仅运行在 Node.js 上的传统后端服务，它的 API 简单且社区资源丰富。如果迁移成本过高，继续使用它是可以的，但务必注意配置安全选项。

node-jose 建议逐步淘汰 🕰️。除非你有明确的兼容性需求，否则应迁移至 jose。jose 由同一作者维护，代表了最新的技术方向。

jws 和 jwa 是构建块 🧱。不要直接用它们来处理用户身份验证。仅在你需要实现非标准的 JWT 扩展或底层加密工具时使用。

核心原则：安全优于便利。选择默认禁止不安全算法的库，并始终在验证时显式指定允许的算法列表。