解决Node.js应用中“jwt must be provided”错误

在Node.js后端开发中，JWT（JSON Web Token）是常用的用户身份认证方案。不少开发者在使用JWT相关逻辑时，会遇到jwt must be provided的错误提示，这个错误通常和JWT的校验、解析流程直接相关，本文会梳理常见的触发场景和对应的解决方法。

错误产生的核心原因

这个错误的本质是JWT相关的处理函数没有接收到有效的token字符串，通常出现在调用jsonwebtoken库的verify方法，或者自定义的中间件解析token时参数缺失的场景。常见的触发场景有以下几个：

• 前端请求时没有携带token，或者携带的token格式不符合后端要求
• 后端从请求头、请求体中提取token的逻辑存在漏洞，没有正确拿到token值
• token提取逻辑执行后，获取到的值为空、undefined或者不符合JWT格式
• 调用verify方法时，误将空值或者非字符串类型的值作为参数传入

常见场景与解决方法

场景1：请求未携带token或token格式错误

很多后端接口要求前端在请求头的Authorization字段中携带token，格式通常是Bearer。如果前端没有添加这个请求头，或者格式写错（比如少了Bearer前缀、多了多余空格），后端就提取不到有效token。

解决办法是首先确认前端的请求头配置是否正确，以下是前端使用axios发送携带token请求的示例：

// 前端axios请求示例
import axios from 'axios';

// 假设从本地存储中获取token
const token = localStorage.getItem('user_token');

axios.get('http://127.0.0.1:3000/api/user/info', {
  headers: {
    // 注意Bearer后面有一个空格，是标准格式要求
    'Authorization': `Bearer ${token}`
  }
}).then(res => {
  console.log(res.data);
}).catch(err => {
  console.error(err);
});

场景2：后端token提取逻辑错误

如果前端已经正确携带了token，后端提取时还是拿不到，通常是提取逻辑有问题。比如只判断了请求头是否存在，没有处理Bearer前缀，或者从错误的位置提取token。

以下是一个正确的token提取中间件示例，会先判断请求头是否存在，再提取有效token部分：

// 后端提取token的中间件示例，使用express框架
const jwt = require('jsonwebtoken');
const { JWT_SECRET } = require('./config'); // 你自己配置的jwt密钥

function authMiddleware(req, res, next) {
  // 1. 先从Authorization请求头获取原始值
  const authHeader = req.headers.authorization;
  
  // 2. 判断请求头是否存在，且格式是否以Bearer 开头
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ code: 401, msg: '未携带有效的token' });
  }
  
  // 3. 提取Bearer后面的token部分，去掉前缀和可能的多余空格
  const token = authHeader.split(' ')[1]?.trim();
  
  // 4. 再次判断token是否存在，避免取到空值
  if (!token) {
    return res.status(401).json({ code: 401, msg: 'token不能为空' });
  }
  
  try {
    // 5. 校验token，此时传入的token一定是非空字符串，避免jwt must be provided错误
    const decoded = jwt.verify(token, JWT_SECRET);
    // 把解析后的用户信息挂载到req对象上，方便后续接口使用
    req.user = decoded;
    next();
  } catch (err) {
    // token过期或者无效的场景处理
    return res.status(401).json({ code: 401, msg: 'token无效或已过期' });
  }
}

module.exports = authMiddleware;

场景3：路由配置或中间件使用顺序错误

如果需要在多个接口中使用JWT校验，要确认中间件是否正确挂载，并且挂载顺序在接口逻辑之前。如果是全局中间件，要放在路由定义之前；如果是单个接口的中间件，要确保写在接口处理函数前面。

以下是express中正确使用认证中间件的示例：

const express = require('express');
const authMiddleware = require('./middleware/auth');
const userRouter = require('./routes/user');

const app = express();

// 解析post请求的json body，放在路由前面
app.use(express.json());

// 不需要认证的接口，比如登录、注册，放在认证中间件前面
app.post('/api/login', (req, res) => {
  // 登录逻辑，返回token
  const token = jwt.sign({ userId: 1 }, JWT_SECRET, { expiresIn: '7d' });
  res.json({ code: 0, data: { token } });
});

// 需要认证的接口，使用认证中间件
app.use('/api/user', authMiddleware, userRouter);

// 错误捕获中间件，放在最后
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ code: 500, msg: '服务器内部错误' });
});

app.listen(3000, () => {
  console.log('服务启动在3000端口');
});

调试小技巧

如果还是无法定位问题，可以在提取token和调用verify方法的位置添加日志，打印相关值：

• 打印req.headers.authorization，确认请求头是否传递到后端
• 打印提取后的token值，确认是否为空、是否符合JWT格式（三段式，用点分隔）
• 如果是调用第三方JWT库的方法报错，确认传入的参数是否是字符串类型，不是undefined或者null

只要保证调用JWT校验方法时，传入的token是有效的非空字符串，就可以避免“jwt must be provided”这个错误。如果排查后还是有问题，可以检查使用的jsonwebtoken库版本是否过低，或者是否存在其他逻辑覆盖了请求头的值。

Node.jsJWT错误jwt_must_be_providedToken校验Express中间件 本作品最后修改时间：2026-05-22 15:59:51