Python使用BCRYPT模块校验密码哈希值时报错如何解决

问题背景 #

• 基于Python bcrypt 库实现的密码加密流程运行正常，生成的哈希值可正常写入数据库，但调用校验逻辑时触发报错。
• 当前使用的校验函数代码：

def decrypt(password, hashed):
    password=password.encode('utf-8')
    return bcrypt.checkpw(password, hashed)

参数说明：password 为用户输入的明文密码，hashed 为从数据库中读取的已存储哈希值

• 该场景下触发的典型报错为：TypeError: Unicode-objects must be encoded before checking

根因定位 #

bcrypt.checkpw() 方法要求两个传入参数必须均为UTF-8编码的bytes类型，现有代码仅对用户输入的明文密码做了编码转换，从数据库读取的哈希值通常是字符串（str）类型，不满足入参要求，是该类报错最常见的诱因。

修复方案 #

1. 补充哈希值的类型判断与编码逻辑，修正后的代码如下：

def decrypt(password, hashed):
    # 明文密码转bytes格式
    password = password.encode('utf-8')
    # 数据库读取的哈希如果是字符串类型，同步转成bytes格式
    if isinstance(hashed, str):
        hashed = hashed.encode('utf-8')
    return bcrypt.checkpw(password, hashed)

2. 若上述修改后仍报错，按以下顺序排查：
   • 检查数据库存储哈希值的字段长度：bcrypt生成的标准哈希值固定为60字符，字段长度设置小于60会导致存储的哈希被截断，校验时触发格式错误
   • 检查加密存储链路：确认哈希写入数据库前没有做多余的转义、编解码、字符串拼接操作，避免哈希值本身被篡改损坏
   • 检查bcrypt版本：确认加密、校验环境使用的bcrypt大版本一致，跨大版本（如3.x升级到4.x）可能存在少量格式兼容问题

内容的提问来源于stack exchange，提问作者Anij Mehta