echo v5 已移除 middleware.jwt(),须改用 echo-jwt/v4 独立包;tokenlookup 默认仅支持 header:authorization,多位置校验需手动配置;错误响应分 400(解析失败)和 401(签名/时效失败),需 errorhandler 统一处理。

直接用 echojwt.WithConfig(),别碰已删除的 middleware.JWT() —— Echo v5 起它就不存在了,硬写会编译失败或 panic。
为什么 middleware.JWT() 找不到或报错
错误现象是 undefined: middleware.JWT 或 cannot find package "github.com/labstack/echo/middleware"。根本原因:v4 的 middleware 包里没这个函数;v5 更是连整个 middleware 包都重构了,JWT 中间件被物理移除。你不是配置错了,是导入路径和依赖全错了。
- 必须安装独立包:
go get github.com/labstack/echo-jwt/v4(不加/v4会拉错分支) - 导入语句只能是:
import "github.com/labstack/echo-jwt/v4" -
SigningKey类型是interface{},但实际常用[]byte("secret")或返回密钥的KeyFunc
TokenLookup 配置不对,中间件根本不会读 token
TokenLookup 默认值是 "header:Authorization",只从 Authorization: Bearer xxx 提取。如果前端传的是 query:token=xxx 或 cookie:jwt=xxx,中间件压根不触发校验,直接放行——这不是“鉴权通过”,是“跳过鉴权”。
- 传 query 参数:设
TokenLookup: "query:token" - 传 cookie:设
TokenLookup: "cookie:jwt" - 多个位置可选?不行,
echo-jwt/v4不支持 fallback,只能选一个
鉴权失败返回 400 还是 401?取决于哪里出问题
中间件对错误的分类非常机械:
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 请求头完全没有
Authorization字段 → 返回400 Bad Request -
Authorization: Bearer xxx但 token 格式非法(少一段、含非法字符)→ 也是400 - 格式合法但签名错误 /
exp已过 /nbf未生效 → 返回401 Unauthorized
想统一返回 401?必须显式配置 ErrorHandler 捕获所有 err 并手动返回,不能依赖默认行为。
自定义 Claims 和黑名单校验必须链式插入
echo-jwt/v4 只做基础解析和签名验证,不查 Redis、不校验 jti、不支持登出即失效。你需要自己补一层中间件:
- 签发时必须带
jti:claims["jti"] = uuid.NewString() - 黑名单存 Redis,key 为
revoked:{jti},TTL 对齐exp - 在
e.Use(echojwt.WithConfig(...))后,再e.Use(checkBlacklist) - 从 context 取 token:
token := c.Get("user").(*jwt.Token),别重复解析
真正容易被忽略的是时间校验细节:exp 必须是秒级 int64,不是毫秒;alg: none 必须在 KeyFunc 里拒绝;服务端时钟漂移要靠 jwt.WithValidTimeFunc 容忍 ±5s 偏差。










