在 Go 语言中使用 golang-jwt 库配置 HS256 算法时，密钥长度必须至少为 32 字节，否则底层 crypto/hmac 会报错 invalid key size 或导致线上签名校验静默失败。
原因分析
HS256 算法基于 HMAC-SHA256，Go 的 crypto/hmac 底层实现要求密钥长度匹配哈希输出长度，即 256 位（32 字节）。根据 2026 年 4 月 2 日的技术文档记录，若密钥如 "my-secret" 仅 9 字节，底层会进行静默截断或补零，导致本地测试通过但线上环境因 Go 版本差异校验失败。此外，旧版 github.com/dgrijalva/jwt-go 已归档，其默认不校验 alg 字段，攻击者可篡改为 none 导致签名失效。
解决方案
1. 生成合规密钥
禁止硬编码简单字符串，应使用命令 openssl rand -base64 32 生成随机密钥，或通过 make([]byte, 32) 配合 rand.Read 生成。密钥需从环境变量 os.Getenv("JWT_SECRET") 读取，生产环境建议长度≥32 字节。
2. 选用正确库版本
必须使用 github.com/golang-jwt/jwt/v5，避免使用无/v5 后缀的 v4 版本或已归档的 dgrijalva 库。解析时需显式指定算法：jwt.ParseWithClaims(tokenStr, &CustomClaims{}, keyFunc, jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}))。
3. 正确传递密钥函数
token.SignedString() 要求传入 func() (interface{}, error) 类型，直接传字符串会报错 key is of invalid type。正确写法为闭包返回 []byte：func() (interface{}, error) { return []byte(secret), nil }。
注意事项
1. 校验逻辑陷阱：仅判断 err == nil 不够，必须检查 token.Valid，否则过期 token 仍可能进入业务逻辑。2. 时间校验：标准字段 exp/iat 不会自动校验，需手动调用 claims.VerifyExpiresAt(time.Now().UTC(), true) 防止时区偏差。3. 错误处理：解析失败需做类型断言 if ve, ok := err.(*jwt.ValidationError); ok {}，区分 ValidationErrorExpired 或 ValidationErrorSignatureInvalid。
参考来源
来源：PHP 中文网 - Golang Gin 如何做 JWT 登录认证_Golang Gin JWT 教程【推荐】
来源：Go-zero 实战文档 - 5 分钟搞定 JWT 鉴权配置 (含常见错误排查)
来源：Golang 初级实战 - 实现一个简单的 JWT 生成与校验
原文链接：https://www.zjcp.cc/ask/9652.html