Echo框架JWT登录认证实战-Golang-PHP中文网

echo-jwt/v4必须单独安装，因JWT中间件自Echo v4.10.0起已从核心移除；需执行go get github.com/labstack/echo-jwt/v4并使用其JWTWithConfig配置，不可再用echo.MiddlewareJWT或内置middleware/jwt.go。

echo框架jwt登录认证实战

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` 头

前端（如 axios）默认只读取响应头里的 Authorization 字段来自动携带后续请求。如果后端只在 JSON body 里返回 {"token": "xxx"}，前端还得手动提取并拼接 header，容易出错。

推荐在登录成功后，同时写 body 和 header：

Echo框架 5.1.0

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

下载

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