必须显式安装github.com/labstack/echo-jwt/v4并确保Echo v4.10.0+,Authorization头需严格为"Bearer "格式,密钥与算法必须完全匹配,且须用类型断言捕获echojwt.UnauthorizedError。

JWT中间件未正确安装或版本不匹配
Echo官方已将JWT中间件从核心移除,直接 go get github.com/labstack/echo 不会包含JWT支持。若仍用旧版文档照搬,会遇到 undefined: middleware.JWT 或运行时 panic。
- 必须显式安装独立包:
go get github.com/labstack/echo-jwt/v4(注意/v4后缀,v3 与 v4 的 API 不兼容) - v4 要求 Echo v4.10.0+,低于此版本会报
cannot use jwt.WithConfig(...) (value of type jwt.Config) as echo.MiddlewareFunc - 导入路径必须为
github.com/labstack/echo-jwt/v4,写成echo-jwt或echo-jwt/v3都会导致类型不匹配
Authorization头解析失败导致401
echo-jwt 默认只从 Authorization 请求头提取 Bearer Token,且严格要求格式为 Bearer <token></token>。任何偏差都会触发 credentials_required 或 credentials_bad_format 错误,返回 401。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 客户端必须发送标准头:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...,不能省略空格、大小写错(如authorization)、或漏掉Bearer前缀 - echo-jwt 不自动兼容
X-API-Key或 query 参数,若需多源 token,得自己写前置中间件统一注入到Authorization头 - 调试时可用
c.Request().Header.Get("Authorization")打印原始值,确认是否被代理/网关剥离或改写
密钥或算法配置错误引发SignatureInvalid
JWT签名验证失败时,echo-jwt 抛出的错误通常不带具体原因,只返回 401 或 500,实际是 jwt.ParseError 被静默吞掉。常见根源是密钥或算法不一致。
- 签发时用
HS256+ 字符串密钥,验证时却传了RS256或空密钥,必然失败;必须确保jwt.WithSigningKey(jwt.SigningKey{Algorithm: "HS256", Key: []byte(os.Getenv("JWT_SECRET"))})中算法和密钥字节完全匹配 - 密钥若来自环境变量,注意前后空格——
os.Getenv("JWT_SECRET")结果带换行或空格会导致签名比对失败 - 使用非对称算法(如
RS256)时,WithSigningKey的Key必须是*rsa.PrivateKey或*ecdsa.PrivateKey,不能传 PEM 字符串
自定义错误处理没接住UnauthorizedError
echo-jwt 内部抛出的是 echo-jwt.UnauthorizedError(不是标准 error),若全局错误处理器只判断 err.Error() 或 errors.Is(err, xxx),会漏掉它,导致 500 而非预期的 401。
- 必须用类型断言捕获:
if e, ok := err.(*echojwt.UnauthorizedError); ok { ... } -
e.Code是字符串(如"invalid_token"),可用于区分场景;e.Message是原始错误信息,不要直接返回给前端 - 未处理的
UnauthorizedError会继续冒泡,最终由 Echo 默认 500 处理器响应,掩盖真实问题
jwt.io 手动解码 token 确认签名和 payload 正确性,再检查服务端密钥加载逻辑。

















