echo-jwt/v4必须单独安装，因JWT中间件自Echo v4.10.0起已从核心移除；需执行go get github.com/labstack/echo-jwt/v4并使用其JWTWithConfig配置，不可再用echo.MiddlewareJWT或内置middleware/jwt.go。
echo-jwt/v4 必须单独安装，不能直接用 echo 内置中间件
从 Echo v4.10.0 起，JWT 中间件已从核心移除。如果你还按旧教程写 echo.MiddlewareJWT(...) 或在 middleware/ 目录下找 jwt.go，会编译失败或 panic。
正确做法是显式引入独立包：
go get github.com/labstack/echo-jwt/v4
注意版本号必须带 /v4，否则导入后类型不匹配（比如 echo-jwt v3 的配置结构体名和 v4 不同）。
- 导入时用
github.com/labstack/echo-jwt/v4，不是github.com/labstack/echo/v4/middleware - 初始化中间件必须传入密钥，且类型为
jwt.WithSigningKey(jwt.SigningMethodHS256, []byte("your-secret")) - 密钥长度要符合算法要求：HS256 至少 32 字节，硬编码字符串建议用
os.Getenv("JWT_SECRET")加载
登录接口返回 token 时，别漏掉 Authorization: Bearer <token></token> 头
前端（如 axios）默认只读取响应头里的 Authorization 字段来自动携带后续请求。如果后端只在 JSON body 里返回 {"token": "xxx"}，前端还得手动提取并拼接 header，容易出错。
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
推荐在登录成功后，同时写 body 和 header：
func login(c echo.Context) error {
// ... 验证用户名密码
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
"user_id": 123,
"exp": time.Now().Add(time.Hour).Unix(),
})
signedToken, _ := token.SignedString([]byte(os.Getenv("JWT_SECRET")))
c.Response().Header().Set("Authorization", "Bearer "+signedToken)
return c.JSON(http.StatusOK, map[string]string{"token": signedToken})
}
- 前端 axios 可配
axios.defaults.headers.common['Authorization'] = 'Bearer ' + token，但更稳的是服务端主动设 header - 不要用
SetCookie存 token —— JWT 本意是无状态，放 Cookie 反而增加 CSRF 风险，除非你明确需要 HttpOnly + SameSite 保护 - 若用
echo-jwt中间件校验，它默认只检查Authorization: Bearer xxx，不识别X-Auth-Token等自定义头
分组路由 + JWT 中间件的典型写法
JWT 认证不该套在整个应用上，否则登录接口自己也会被拦截。必须把认证中间件绑定到受保护的子路由组，比如 /api/v1，而 /login、/register 留在根组。
e := echo.New()
// 公共路由
e.POST("/login", login)
e.POST("/register", register)
// 受保护路由组
v1 := e.Group("/api/v1")
v1.Use(echojwt.JWTWithConfig(echojwt.Config{
SigningKey: jwt.SigningKey{Key: []byte(os.Getenv("JWT_SECRET")), Method: jwt.SigningMethodHS256},
ContextKey: "user", // 解析后存进 c.Get("user") 的 key 名
}))
v1.GET("/profile", getProfile)
v1.PUT("/settings", updateSettings)
-
ContextKey默认是"user"，但你可以改成"claims"或其他，只要和 handler 里c.Get(...)一致 - handler 中获取用户 ID 应该是：
claims := c.Get("user").(*jwt.Token).Claims.(jwt.MapClaims); userID := int(claims["user_id"].(float64))—— 注意类型断言链，float64是 json number 的默认解码结果 - 别在中间件里做数据库查用户：JWT 本身应包含必要声明（如
user_id），查库逻辑留在业务 handler 里
常见 401 错误原因和调试路径
调用受保护接口返回 401 却不知哪步挂了？按顺序排查：
- 前端是否真发了
Authorization: Bearer xxx？用浏览器 DevTools → Network → Headers 确认 - token 是否过期？
echo-jwt默认校验exp、nbf、iat，任意一个失败都拒掉，错误日志默认不输出详情 - 密钥是否一致？登录生成用
[]byte("a")，中间件配置却用[]byte("b")，必然失败 - 是否跨域没配好？CORS 中间件必须在 JWT 之前注册，否则预检请求（OPTIONS）直接 401，根本进不到 JWT 校验
- token 字符串是否被 URL 编码污染？比如前端从 query string 拿 token 后没
decodeURIComponent就直接塞 header
JWT 的“无状态”优势全靠签名和时间戳验证，一旦密钥泄露或时钟偏差大，整个链路就不可信。生产环境务必用 NTP 同步服务器时间，并轮换密钥。
