Echo v5起已彻底移除内置JWT中间件,middleware.JWT()会编译失败或panic;必须使用github.com/labstack/echo-jwt/v4,通过echojwt.WithConfig()配置并注册,SigningKey等需与签发逻辑严格对齐。

直接说结论:Echo v5 起已彻底移除内置 JWT 中间件,middleware.JWT() 会编译失败或 panic;必须用 github.com/labstack/echo-jwt/v4,且初始化方式不是函数调用,而是 echojwt.WithConfig()。
为什么 middleware.JWT() 找不到或报 undefined
根本原因是:v4 的 github.com/labstack/echo/middleware 包里压根没这个函数;v5 更是连整个 middleware 包都重构了,JWT 已物理删除。错误现象常见为:undefined: middleware.JWT 或 cannot find package "github.com/labstack/echo/middleware"。
正确导入路径只能是:github.com/labstack/echo-jwt/v4(注意 /v4 后缀);安装命令必须带版本:
go get github.com/labstack/echo-jwt/v4
不加 /v4 会拉错分支,导致类型不兼容或找不到符号。
echojwt.WithConfig() 的关键配置项
不能写成 e.Use(middleware.JWT(...)),必须先构造中间件实例再传入 e.Use()。签名密钥类型声明为 interface{},但实际常用 []byte 或返回 interface{} 的 KeyFunc 函数。
-
SigningKey:最简场景下直接传[]byte("your-secret-key"),密钥长度建议 ≥32 字节(HS256) -
TokenLookup:默认是"header:Authorization";若前端传的是query:token或cookie:jwt,必须显式配置,否则中间件根本不读 token -
ErrorHandler:默认对无 token 字段返回 400,对过期/签名错返回 401;想统一返回 401,必须用此字段捕获所有err并手动c.JSON(401, ...)
签发与验证逻辑必须严格对齐
echo-jwt 底层调用 jwt.ParseWithClaims,而它默认行为很危险:
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
-
exp必须是秒级int64,不是毫秒——否则刚签发就报"token is expired" - 不设
KeyFunc时无法拒绝alg: none攻击,必须在KeyFunc里校验token.Method - 时间校验默认无容错,服务端时钟漂移会导致误拒;应传
jwt.WithValidTimeFunc加 ±5s 偏差容忍
推荐的 KeyFunc 写法:
func(token *jwt.Token) (interface{}, error) {
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
}
return jwtKey, nil
}
黑名单校验不能依赖 echo-jwt 默认行为
echo-jwt/v4 设计就是无状态的,只做签名和时间字段验证,完全不查 Redis 或 DB。要支持登出即失效,必须额外加一层中间件链在 echojwt.WithConfig() 之后。
操作要点:
- 签发时务必设置
jti字段:claims["jti"] = uuid.NewString() - 黑名单 key 格式建议为
revoked:{jti},TTL 与 tokenexp对齐 - 自定义中间件里直接从
c.Get("user")取已解析的*jwt.Token,别重复解析 - Redis 查询用
SET revoked:{jti} "" EX 900 NX写入,避免并发漏检
真正容易被忽略的是:时间校验容错、alg 检查、以及黑名单写入的原子性——这三处任一缺失,都会让 JWT 安全模型形同虚设。










