Echo框架JWT接口认证教程-Golang-PHP中文网

echo v5起已彻底移除内置jwt中间件，必须使用独立包github.com/labstack/echo-jwt/v4，否则middleware.jwt()会编译失败或panic；正确用法是e.use(echojwt.withconfig(...))，且signingkey等配置需严格匹配签发逻辑。

echo框架jwt接口认证教程

JWT 中间件在 Echo 中已从核心移除，必须用 github.com/labstack/echo-jwt/v4 独立包，否则 middleware.JWT() 会编译失败或运行时 panic。

为什么 `middleware.JWT()` 找不到或报错

Echo v5 起彻底移除了内置 JWT 中间件。如果你还在用 github.com/labstack/echo/v4 或更早版本的 middleware.JWT()，那代码已经失效——它不是被“隐藏”，而是物理删除了。

错误现象：undefined: middleware.JWT 或 cannot find package "github.com/labstack/echo/middleware"
根本原因：v4 的 middleware 包里没这个函数；v5 更是连整个 middleware 包都重构了
正确导入路径只能是：github.com/labstack/echo-jwt/v4（注意 /v4 后缀）
安装命令必须带版本：go get github.com/labstack/echo-jwt/v4，不加 /v4 会拉错分支

`echo-jwt/v4` 的标准初始化方式

不能直接 e.Use(middleware.JWT(...))，要先构造中间件实例，再传给 e.Use()。签名密钥类型必须是 interface{}，但实际常用 []byte 或实现 jwt.Keyfunc 的函数。

Echo框架 5.1.0

Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。

下载

最简用法（HS256 + 静态密钥）：

e.Use(echojwt.WithConfig(echojwt.Config{
    SigningKey: []byte("your-secret-key"),
}))

推荐用法（支持动态密钥、自定义错误响应）：

e.Use(echojwt.WithConfig(echojwt.Config{
    SigningKey: []byte("your-secret-key"),
    ErrorHandler: func(c echo.Context, err error) error {
        return c.JSON(http.StatusUnauthorized, map[string]string{"error": "invalid or expired token"})
    },
    TokenLookup: "header:Authorization",
}))

TokenLookup 默认是 "header:Authorization"，若前端传的是 query:token 或 cookie:jwt，必须显式配置，否则中间件根本不会去读

鉴权失败时返回 401 还是 400？看哪里出问题

中间件对错误的分类很机械，完全取决于请求里有没有尝试提供 token：

请求头完全没有 Authorization 字段 → 返回 400 Bad Request（echo-jwt 认为这是客户端使用错误）
有 Authorization: Bearer xxx，但 token 格式非法（比如少一段、含非法字符）→ 也是 400
token 格式合法但签名错误 / 过期 / exp 已到 → 返回 401 Unauthorized
想统一成 401？必须用 ErrorHandler 捕获所有 err 并手动返回，不能依赖默认行为

WebSocket 接口不能套用 JWT 中间件

WebSocket 握手阶段（HTTP Upgrade 请求）必须在 upgrader.Upgrade() 前完成鉴权，而 echo-jwt 是标准 HTTP 中间件，只对普通 handler 生效，对 WebSocket 升级流程完全无感知。

错误写法：e.GET("/ws", jwtMiddleware, wsHandler) —— 中间件执行时响应头可能已被写入，Upgrade() 必然失败
正确做法：用原生 http.HandlerFunc 提前解析 r.Header.Get("Authorization") 或 r.URL.Query().Get("token")，校验通过后再调 upgrader.Upgrade()
别忘了：失败时直接 http.Error(w, "Unauthorized", http.StatusUnauthorized)，绝不能等升级完再关连接

真正容易被忽略的点是密钥管理——硬编码 []byte("secret") 在生产环境等于裸奔；SigningKey 应该从环境变量或密钥管理服务加载，且必须确保和签发 token 时用的是同一把钥匙。算法也要核对清楚，默认 HS256，如果用 RS256 就得换 SigningMethod 和 SigningKey 类型。