Node.js crypto 模块哈希用法指南 (解决 is not a function 错误) – wiki基地

Node.js `crypto` 模块哈希用法深度解析：告别 “is not a function” 错误

在现代软件开发中，数据的完整性和安全性至关重要。无论是存储用户密码、验证文件下载，还是在网络通信中确保数据未被篡改，哈希（Hashing）都扮演着核心角色。Node.js 作为一款强大的后端运行时环境，通过内置的 crypto 模块为我们提供了丰富的加密和解密能力，其中就包括了各种哈希算法的实现。

然而，对于初学者（甚至有时是经验丰富的开发者）来说，在使用 crypto 模块进行哈希操作时，可能会遇到各种问题，其中最常见且令人困惑的莫过于 “TypeError: … is not a function”。本文将深入探讨 Node.js crypto 模块中哈希功能的用法，详细讲解不同场景下的哈希实现，并重点分析和解决导致 “is not a function” 错误的原因及其调试方法。

第一章：理解哈希（Hashing）的基本概念

在深入 crypto 模块之前，我们有必要回顾一下哈希的基本原理和用途。

1.1 什么是哈希函数？

哈希函数（Hash Function）是一种数学算法，它接收任意大小的输入数据（称为“消息”或“输入”），并产生一个固定大小的输出（称为“哈希值”、“散列值”或“消息摘要”）。理想的哈希函数应该具备以下关键属性：

确定性 (Deterministic): 相同的输入始终产生相同的输出。
高效性 (Efficient): 计算哈希值应该非常快速。
单向性 (One-Way): 从哈希值很难或几乎不可能反推出原始输入。
弱碰撞抵抗性 (Weak Collision Resistance / Second Pre-image Resistance): 对于给定的输入 x，找到另一个不同的输入 y 使得 hash(x) = hash(y) 是计算上不可行的。
强碰撞抵抗性 (Strong Collision Resistance / Collision Resistance): 找到任意两个不同的输入 x 和 y 使得 hash(x) = hash(y) 是计算上不可行的。

1.2 常见的哈希算法

Node.js crypto 模块支持多种哈希算法，其中一些是广泛应用的工业标准：

MD5 (Message Digest Algorithm 5): 曾广泛使用，但因其存在严重的碰撞漏洞，现在不建议用于安全性要求高的场景，特别是密码存储和数字签名。主要用于文件校验和等完整性检查（但需注意，恶意方可以构造相同校验和的不同文件）。
SHA-1 (Secure Hash Algorithm 1): 类似于MD5，也已被证明存在碰撞漏洞，不建议用于安全性要求高的场景。
SHA-2 系列 (SHA-256, SHA-384, SHA-512等): 这是目前广泛推荐使用的哈希算法家族。SHA-256 生成 256 位（32字节）的哈希值，SHA-512 生成 512 位（64字节）。它们被认为是安全的，用于各种场景，如数字证书、区块链等。
SHA-3 系列 (SHA3-256, SHA3-512等): 作为 SHA-2 的替代和补充而设计，提供不同的结构，具有良好的安全性。
其他: Node.js crypto 还可能支持一些其他的算法，具体取决于 Node.js 版本和底层的 OpenSSL 库。可以通过 crypto.getHashes() 方法查看当前环境支持的所有哈希算法列表。

1.3 哈希的应用场景

数据完整性校验: 通过比较数据的哈希值来判断数据是否在传输或存储过程中被修改。
密码存储 (结合盐值和迭代): 直接存储密码的哈希值是不安全的。正确的做法是为每个密码生成一个唯一的“盐”（Salt），将盐和密码混合后进行多次迭代哈希（使用专门的密码哈希函数，如 bcrypt, scrypt, PBKDF2），然后存储盐值和最终的哈希值。Node.js crypto 提供了 PBKDF2 和 scrypt 的实现。
数字签名: 哈希是数字签名过程的一部分。对消息进行哈希处理，然后使用私钥加密哈希值，形成签名。
数据去重: 在数据库或存储系统中，可以使用哈希值来快速检测重复数据。

第二章：Node.js `crypto` 模块入门

Node.js 的 crypto 模块是内置的，无需额外安装。只需使用 require 语句即可引入：

javascript const crypto = require('crypto');

crypto 模块提供了多种创建不同加密对象的方法。对于哈希操作，我们主要关注以下方法：

crypto.createHash(algorithm): 创建一个哈希对象，用于计算给定算法的哈希值。
crypto.createHmac(algorithm, key): 创建一个 HMAC（基于哈希的消息认证码）对象。HMAC 是一种带密钥的哈希，用于验证数据的完整性和认证消息的来源。
crypto.scrypt(password, salt, keylen[, options], callback) / crypto.scryptSync(...): 用于基于密码和盐值派生密钥，适用于密码存储等需要计算密集型哈希的场景。
crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) / crypto.pbkdf2Sync(...): 另一种常用的密码学密钥派生函数，类似于 scrypt。

本篇文章的重点是使用 createHash 和 createHmac 进行基本的哈希计算，以及如何正确使用 scrypt 或 pbkdf2 进行密码哈希（虽然它们是密钥派生函数，但在密码安全存储中常被归类为“哈希”）。

第三章：使用 `crypto.createHash()` 进行基本哈希

crypto.createHash() 是进行标准哈希计算的主要方法。它创建一个 Hash 对象，你可以向这个对象“喂入”数据，然后得到最终的哈希结果。

基本流程:

调用 crypto.createHash(algorithm) 创建一个哈希对象，指定使用的算法（如 ‘sha256’, ‘md5’ 等）。
调用 hash.update(data[, inputEncoding]) 方法向哈希对象添加要处理的数据。可以多次调用 update 来逐步处理数据。
调用 hash.digest([outputEncoding]) 方法计算最终的哈希值。注意：调用 digest() 后，哈希对象会进入一个不可用的状态，不能再调用 update() 或 digest()。

3.1 示例：计算字符串的 SHA-256 哈希值

“`javascript
const crypto = require(‘crypto’);

const data = ‘Hello, Node.js Hashing!’;
const algorithm = ‘sha256’;

try {
// 1. 创建哈希对象
const hash = crypto.createHash(algorithm);

// 2. 添加数据
// update 方法接受字符串或 Buffer。如果是字符串，建议明确指定编码，
// 否则默认使用 'utf8'。
hash.update(data, 'utf8');

// 3. 计算并获取哈希值
// digest 方法可以指定输出格式，如 'hex', 'base64', 'binary'。
// 如果不指定，默认为 'binary' (Buffer)。
const hashHex = hash.digest('hex'); // 常用十六进制表示

console.log(`${algorithm} 哈希值 (十六进制): ${hashHex}`);

const hashBase64 = hash.digest('base64'); // Base64 表示
console.log(`${algorithm} 哈希值 (Base64): ${hashBase64}`);

} catch (error) {
console.error(“哈希计算出错:”, error);
}
“`

运行上述代码，你会看到类似以下的输出（哈希值是固定的）：

sha256 哈希值 (十六进制): 7b72f710127144b7b429e7d1e1f3c8a0a4e0e9e6d1e1f3c8a0a4e0e9... (实际值会更长) sha256 哈希值 (Base64): e3L3EBd... (实际值会更长)

3.2 示例：分块处理大数据的哈希

如果需要哈希的数据非常大，一次性加载到内存可能不现实。update() 方法可以分块处理数据，这在处理文件流时非常有用。

“`javascript
const crypto = require(‘crypto’);
const fs = require(‘fs’);

const filePath = ‘path/to/your/large/file’; // 替换为你的大文件路径
const algorithm = ‘sha256’;

try {
const hash = crypto.createHash(algorithm);
const stream = fs.createReadStream(filePath);

stream.on('data', (chunk) => {
    // 每次读取一块数据，就更新哈希对象
    hash.update(chunk);
});

stream.on('end', () => {
    // 数据流读取完毕，计算最终哈希值
    const fileHash = hash.digest('hex');
    console.log(`文件 ${filePath} 的 ${algorithm} 哈希值: ${fileHash}`);
});

stream.on('error', (err) => {
    console.error(`读取文件出错: ${err}`);
});

} catch (error) {
console.error(“创建哈希或流出错:”, error);
}
“`

这个例子展示了如何通过数据流将文件内容逐步馈送给哈希对象。update() 方法内部会累积处理所有传入的数据块，直到 digest() 被调用。

第四章：使用 `crypto.createHmac()` 进行带密钥的哈希 (HMAC)

HMAC 是一种使用密钥来增强哈希安全性的机制。它不仅验证数据的完整性，还验证数据的来源（因为只有知道密钥的人才能生成有效的 HMAC）。HMAC 广泛用于 API 签名、会话验证等场景。

基本流程:

调用 crypto.createHmac(algorithm, key) 创建一个 HMAC 对象，指定算法和秘密密钥。密钥可以是字符串、Buffer、TypedArray 或 DataView。如果是字符串，默认使用 ‘utf8’ 编码。
调用 hmac.update(data[, inputEncoding]) 方法向 HMAC 对象添加要处理的数据。
调用 hmac.digest([outputEncoding]) 方法计算最终的 HMAC 值。同样，digest() 后对象会进入不可用状态。

4.1 示例：计算字符串的 HMAC-SHA256 值

“`javascript
const crypto = require(‘crypto’);

const data = ‘This is a secret message.’;
const key = ‘mySuperSecretKey’; // 共享的秘密密钥
const algorithm = ‘sha256’;

try {
// 1. 创建 HMAC 对象，同时提供算法和密钥
const hmac = crypto.createHmac(algorithm, key);

// 2. 添加数据
hmac.update(data, 'utf8');

// 3. 计算并获取 HMAC 值
const hmacHex = hmac.digest('hex');

console.log(`数据 "${data}" 的 HMAC-${algorithm} 值 (密钥: "${key}"): ${hmacHex}`);

} catch (error) {
console.error(“HMAC 计算出错:”, error);
}
“`

4.2 示例：验证 HMAC

验证 HMAC 的过程是接收方使用相同的算法和密钥，对原始数据重新计算 HMAC，然后将计算结果与接收到的 HMAC 进行比较。

“`javascript
const crypto = require(‘crypto’);

const receivedData = ‘This is a secret message.’;
const receivedHmac = ‘ab10c3…’; // 假设这是从发送方收到的 HMAC 值 (替换为实际值)
const key = ‘mySuperSecretKey’; // 接收方也必须拥有相同的密钥
const algorithm = ‘sha256’;

try {
const hmac = crypto.createHmac(algorithm, key);
hmac.update(receivedData, ‘utf8’);
const calculatedHmac = hmac.digest(‘hex’);

console.log(`接收到的 HMAC: ${receivedHmac}`);
console.log(`计算的 HMAC: ${calculatedHmac}`);

// 使用 crypto.timingSafeEqual 进行比较，防止时序攻击
const receivedBuffer = Buffer.from(receivedHmac, 'hex');
const calculatedBuffer = Buffer.from(calculatedHmac, 'hex');

// 比较两个 Buffer 是否相等
if (receivedBuffer.length === calculatedBuffer.length &&
    crypto.timingSafeEqual(receivedBuffer, calculatedBuffer)) {
    console.log("HMAC 验证成功：数据完整且来自可信源。");
} else {
    console.log("HMAC 验证失败：数据可能已被篡改或来源不可信。");
}

} catch (error) {
console.error(“HMAC 验证出错:”, error);
}
“`

重要提示： 比较两个哈希值（或 HMAC 值）时，应使用 crypto.timingSafeEqual() 方法，而不是简单的 === 运算符。简单的 === 比较可能会因为不同长度或内容的不匹配位置而提前返回结果，泄露关于哈希值的时序信息，这可能被攻击者利用进行时序攻击。timingSafeEqual() 无论比较结果如何，总是花费相同的时间，从而避免时序泄露。

第五章：密码哈希 (使用 PBKDF2 或 Scrypt)

如前所述，对于密码存储，简单地使用 SHA-256 等通用哈希算法是不足够的。因为这些算法被设计得非常快速，攻击者可以利用高性能计算设备进行大规模的字典攻击或彩虹表攻击。密码哈希需要使用专门的密钥派生函数 (KDF)，它们被设计得计算缓慢、需要大量内存或多次迭代，以此来抵御暴力破解。

Node.js crypto 模块提供了 pbkdf2 和 scrypt 这两个强大的 KDF。它们都需要一个盐值 (Salt) 和迭代次数 (Iterations) 或成本因子 (Cost factors)。

盐值 (Salt): 一个随机生成的字符串，与密码一起输入到 KDF 中。盐值保证了即使两个用户设置了相同的密码，最终生成的哈希值也会不同。盐值需要与密码哈希值一起存储。
迭代次数/成本因子: 控制 KDF 的计算强度。值越高，计算越慢，抵御攻击的能力越强，但同时也会增加服务器的负担。需要根据硬件性能进行权衡和调整。

这两种 KDF 的操作通常是异步的，因为它们的设计目标就是耗时，如果在主线程同步执行会阻塞整个应用。Node.js 也提供了同步版本 (pbkdf2Sync, scryptSync)，但强烈建议在实际应用中使用异步版本，以免阻塞事件循环。

5.1 使用 crypto.scrypt() 进行密码哈希和验证

Scrypt 是一种现代的 KDF，它不仅增加了计算开销，还增加了内存开销，这使得它比 PBKDF2 更能抵抗基于 GPU 的并行攻击。

“`javascript
const crypto = require(‘crypto’);

// — 密码哈希 —
function hashPassword(password) {
return new Promise((resolve, reject) => {
// 1. 生成随机盐值 (建议使用 16 字节或更多)
const salt = crypto.randomBytes(16).toString(‘hex’);
const passwordBuffer = Buffer.from(password, ‘utf8’);
const saltBuffer = Buffer.from(salt, ‘hex’);

    // 2. 使用 scrypt 计算哈希值
    // 参数: 密码, 盐, 期望的输出密钥长度, scrypt 参数 (n, r, p), 回调函数
    // n (cpu/memory cost): 必须是 2^N (N > 1). 越高越慢，越高越好。
    // r (block size): 影响内存访问顺序和缓存的使用。
    // p (parallelization factor): 影响并行性。
    // 这些参数需要根据你的硬件进行性能测试和调整。
    const scryptOptions = { N: 16384, r: 8, p: 1 }; // 示例参数，实际应用需调整
    const keylen = 64; // 期望的哈希值长度 (例如 64 字节 / 128 十六进制字符)

    crypto.scrypt(passwordBuffer, saltBuffer, keylen, scryptOptions, (err, derivedKey) => {
        if (err) {
            return reject(err);
        }
        // derivedKey 是 Buffer。将盐值和哈希值拼接起来存储
        // 常见的格式是：salt.hex$derivedKey.hex
        const hashedPassword = `${salt}$${derivedKey.toString('hex')}`;
        resolve(hashedPassword);
    });
});

}

// — 密码验证 —
function verifyPassword(password, hashedPasswordWithSalt) {
return new Promise((resolve, reject) => {
// 1. 从存储的哈希值中分离盐值和哈希值
const parts = hashedPasswordWithSalt.split(‘$’);
if (parts.length !== 2) {
return reject(new Error(“Invalid stored password format.”));
}
const salt = parts[0];
const storedHash = parts[1];

    const passwordBuffer = Buffer.from(password, 'utf8');
    const saltBuffer = Buffer.from(salt, 'hex');
    const storedHashBuffer = Buffer.from(storedHash, 'hex');
    const keylen = storedHashBuffer.length; // 使用存储的哈希值长度作为 keylen

    // 2. 使用相同的参数和盐值，对用户输入的密码重新计算哈希值
    // 注意：使用相同的 scryptOptions 参数！实际应用中可能需要存储这些参数或使用标准格式
    const scryptOptions = { N: 16384, r: 8, p: 1 }; // 示例参数，必须与哈希时使用的参数一致

    crypto.scrypt(passwordBuffer, saltBuffer, keylen, scryptOptions, (err, derivedKey) => {
        if (err) {
            return reject(err);
        }

        const calculatedHashBuffer = derivedKey;

        // 3. 使用 timingSafeEqual 比较计算出的哈希值与存储的哈希值
        if (crypto.timingSafeEqual(storedHashBuffer, calculatedHashBuffer)) {
            resolve(true); // 密码匹配
        } else {
            resolve(false); // 密码不匹配
        }
    });
});

}

// — 使用示例 —
const userPassword = ‘mySecurePassword123’;

hashPassword(userPassword)
.then(hashedPwd => {
console.log(“原始密码:”, userPassword);
console.log(“加盐哈希后存储的值:”, hashedPwd);

    // 模拟用户登录时验证密码
    const userInputPasswordAttempt = 'mySecurePassword123'; // 正确的尝试
    // const userInputPasswordAttempt = 'wrongPassword'; // 错误的尝试

    return verifyPassword(userInputPasswordAttempt, hashedPwd);
})
.then(isMatch => {
    console.log(`密码验证结果: ${isMatch ? '匹配' : '不匹配'}`);
})
.catch(err => {
    console.error("处理密码时发生错误:", err);
});

“`

PBKDF2 的用法与 scrypt 类似，只是参数不同。PBKDF2 需要指定迭代次数 (iterations) 而不是 N, r, p 参数。可以查阅 Node.js 官方文档了解 crypto.pbkdf2 的详细参数。

重要提示： 无论使用 scrypt 还是 pbkdf2，请不要硬编码 cost factors (N, r, p) 或 iterations。随着计算能力的提升，你需要定期评估并可能增加这些值。许多库会使用一种标准格式将这些参数编码到最终的哈希字符串中，方便验证时读取。或者，你可以选择使用像 bcrypt 这样的第三方库，它们更专注于密码哈希，并通常提供更简单的 API 和自动化的参数管理。

第六章：解决 “TypeError: … is not a function” 错误

现在我们来重点分析并解决在使用 crypto 模块哈希时可能遇到的 “TypeError: … is not a function” 错误。这个错误通常意味着你尝试调用一个不存在或不是函数的方法。在使用 crypto 模块时，最常见的原因是将方法调用链错误地应用到了错误的对象上。

错误场景一：在 digest() 的结果上调用哈希对象的方法

这是最常见的错误。记住：digest() 方法会结束哈希计算，并返回最终的哈希值。这个返回值是一个字符串或 Buffer，它不再是哈希对象。如果你尝试在这个返回值上调用 update() 或再次调用 digest()，就会触发 “TypeError: … is not a function”。

错误代码示例:

“`javascript
const crypto = require(‘crypto’);

const data1 = ‘part one ‘;
const data2 = ‘part two’;

try {
const hash = crypto.createHash(‘sha256’);
hash.update(data1, ‘utf8’);

// 错误！这里调用了 digest()，哈希对象 hash 已经完成并释放。
// digest() 返回的是哈希值字符串。
const partialHashHex = hash.digest('hex');

console.log("Partial Hash:", partialHashHex);

// 错误！你不能在一个字符串 (partialHashHex) 上调用 update() 方法。
partialHashHex.update(data2, 'utf8'); // --> TypeError: partialHashHex.update is not a function

// 错误！你不能在一个字符串 (partialHashHex) 上调用 digest() 方法。
const finalHash = partialHashHex.digest('hex'); // --> TypeError: partialHashHex.digest is not a function

} catch (error) {
console.error(“错误发生:”, error);
}
“`

正确做法:

应该在调用 digest() 之前使用 update() 添加所有需要哈希的数据。

“`javascript
const crypto = require(‘crypto’);

const data1 = ‘part one ‘;
const data2 = ‘part two’;

try {
const hash = crypto.createHash(‘sha256’);

// 正确：在调用 digest() 之前多次调用 update()
hash.update(data1, 'utf8');
hash.update(data2, 'utf8');

// 正确：最后一次调用 digest() 获取最终哈希值
const finalHash = hash.digest('hex');

console.log("Final Hash:", finalHash);

} catch (error) {
console.error(“哈希计算出错:”, error);
}
“`

错误场景二：变量未正确赋值或为 undefined/null

如果你尝试在一个尚未被正确初始化或赋值为 crypto.createHash() 或 crypto.createHmac() 返回的哈希/HMAC 对象上的变量上调用方法，也会出现此错误。这通常发生在代码逻辑分支错误、异步回调问题、或者简单的拼写错误导致变量名不正确时。

错误代码示例:

“`javascript
const crypto = require(‘crypto’);

let hashObject; // 变量尚未被赋值

function initializeHash(algorithm) {
// 假设这里根据条件初始化，但如果条件不满足，hashObject 就一直是 undefined
if (algorithm === ‘sha256’) {
// hashObject = crypto.createHash(‘sha256’); // 故意注释掉这行
}
// 如果 algorithm 不是 ‘sha256’，或者上面的行被注释，hashObject 就是 undefined
}

initializeHash(‘md5’); // 调用函数，但 hashObject 未被赋值

try {
// 错误！hashObject 是 undefined，undefined 没有 update 方法
hashObject.update(‘some data’); // –> TypeError: Cannot read properties of undefined (reading ‘update’) 或类似的错误信息
} catch (error) {
console.error(“错误发生:”, error);
}
“`

正确做法:

确保在使用哈希对象之前，它已经被 crypto.createHash() 或 crypto.createHmac() 正确初始化。

“`javascript
const crypto = require(‘crypto’);

    // 确保 hashObject 已经是一个有效的对象
    if (hashObject && typeof hashObject.update === 'function') {
         hashObject.update(data, 'utf8');
         const finalHash = hashObject.digest('hex');
         console.log(`${algorithm} hash of data: ${finalHash}`);
    } else {
         console.error("Failed to create valid hash object."); // 这通常不会发生如果 createHash 成功
    }


} catch (error) {
    console.error("处理数据时发生错误:", error);
}

}

processDataWithHash(‘some data to hash’, ‘sha256’);
processDataWithHash(‘another data’, ‘unknown_algorithm’); // 演示错误处理
“`

错误场景三：方法名拼写错误

简单的拼写错误也会导致 “is not a function” 错误。例如，将 update 写成 updata 或 digest 写成 digiest。

错误代码示例:

“`javascript
const crypto = require(‘crypto’);

try {
const hash = crypto.createHash(‘sha256’);
// 错误！方法名拼写错误
hash.updata(‘some data’); // –> TypeError: hash.updata is not a function
} catch (error) {
console.error(“错误发生:”, error);
}
“`

正确做法:

仔细检查方法名是否与 Node.js crypto 模块文档中的方法名一致。使用支持代码补全功能的编辑器可以帮助避免这类错误。

错误场景四：Node.js 版本兼容性问题 (较少见于核心方法)

虽然 createHash, update, digest 是非常基础和稳定的方法，但在非常老的 Node.js 版本中，某些特定的哈希算法可能不受支持。尝试使用一个不受支持的算法调用 crypto.createHash() 可能会返回 null 或抛出不同的错误，但如果在后续代码中没有检查，可能会间接导致方法调用错误。更可能的是，一些较新的方法（如 scrypt）在早期版本中不存在。

示例 (假设，具体行为取决于版本):

“`javascript
// 假设在某个非常老的 Node.js 版本中不支持 sha3-512
const crypto = require(‘crypto’);

try {
// createHash(‘sha3-512’) 可能返回 null 或抛出错误
const hash = crypto.createHash(‘sha3-512’);

// 如果 hash 是 null...
hash.update('data'); // --> TypeError: Cannot read properties of null (reading 'update')

} catch (error) {
console.error(“错误发生:”, error);
}
“`

正确做法:

查阅 Node.js 官方文档，确认你使用的 Node.js 版本支持你需要的算法和方法。
使用 crypto.getHashes() 动态检查当前环境支持的算法。
在创建哈希/HMAC对象后，进行基本的类型检查（尽管 createHash 和 createHmac 成功时通常会返回正确的对象）。

“`javascript
const crypto = require(‘crypto’);
const algorithm = ‘sha3-512’;

if (!crypto.getHashes().includes(algorithm)) {
console.error(Error: Algorithm "${algorithm}" is not supported in this Node.js version.);
// 可以选择退出或使用备用算法
} else {
try {
const hash = crypto.createHash(algorithm);
hash.update(‘some data’);
const hashHex = hash.digest(‘hex’);
console.log(${algorithm} hash: ${hashHex});
} catch (error) {
console.error(Error creating or using hash with ${algorithm}:, error);
}
}
“`

错误场景五：异步方法混用同步调用

crypto.scrypt() 和 crypto.pbkdf2() 是异步方法（接收回调函数或返回 Promise）。如果你尝试以同步方式调用它们（不提供回调或不使用 .then()/.await 处理 Promise），并且错误地假设它们会立即返回结果对象，然后在这个 undefined 或 Promise 对象上调用后续方法，也会触发错误。

错误代码示例:

“`javascript
const crypto = require(‘crypto’);

const password = ‘test’;
const salt = crypto.randomBytes(16);
const keylen = 64;
const iterations = 100000; // PBKDF2 参数

try {
// 错误！pbkdf2 是异步方法，它返回 undefined 并通过回调函数返回结果。
// storedHashVar 在回调函数执行前就是 undefined。
const storedHashVar = crypto.pbkdf2(password, salt, iterations, keylen, ‘sha512’, (err, derivedKey) => {
if (err) throw err;
// 这个回调函数稍后执行
console.log(‘Async PBKDF2 result:’, derivedKey.toString(‘hex’));
});

// 错误！storedHashVar 是 undefined，undefined 没有 toString 方法。
console.log("Attempting to log sync result:", storedHashVar.toString('hex')); // --> TypeError: Cannot read properties of undefined (reading 'toString')

} catch (error) {
console.error(“错误发生:”, error);
}
“`

正确做法:

使用异步方法时，通过回调函数或 Promise (util.promisify 或内置的 Promise 支持) 来处理结果。

“`javascript
const crypto = require(‘crypto’);
const util = require(‘util’);

// Promisify the async pbkdf2 method
const pbkdf2Async = util.promisify(crypto.pbkdf2);

async function processPasswordAsync(password) {
const salt = crypto.randomBytes(16);
const keylen = 64;
const iterations = 100000;

try {
    // 正确：使用 await 等待 Promise 解决，获取 derivedKey (Buffer)
    const derivedKey = await pbkdf2Async(password, salt, iterations, keylen, 'sha512');

    const hashedPassword = `${salt.toString('hex')}$${derivedKey.toString('hex')}`;
    console.log("Hashed password (async):", hashedPassword);

    // 在这里可以使用 derivedKey 进行后续操作

} catch (error) {
    console.error("Async PBKDF2 error:", error);
}

}

processPasswordAsync(‘myPassword’);

// 或者使用回调风格 (原始API)
crypto.pbkdf2(‘anotherPassword’, salt, iterations, keylen, ‘sha512’, (err, derivedKey) => {
if (err) {
console.error(“Callback PBKDF2 error:”, err);
return;
}
console.log(“Hashed password (callback):”, ${salt.toString('hex')}$${derivedKey.toString('hex')});
});
“`

调试 “is not a function” 错误的策略：

看清错误信息: 错误信息会告诉你哪个对象或变量没有你尝试调用的函数。例如，TypeError: someVar.update is not a function 明确指示 someVar 不是一个具备 update 方法的对象。
检查出错行的变量类型: 在出错行之前，使用 console.log(typeof variableName) 和 console.log(variableName) 打印出相关变量的类型和值。这能帮助你立即发现变量是 undefined, null, 一个字符串，一个 Buffer，或者不是你期望的哈希/HMAC对象。
逐步调试: 使用 Node.js 调试器 (如 VS Code 内置调试器) 或在代码中插入 console.log 语句，一步步跟踪代码执行流程，查看变量状态的变化，确定在哪里变量变成了非预期的类型。
检查方法名拼写: 对照官方文档仔细检查所有方法名。
理解 digest() 的作用: 再次强调，digest() 结束哈希计算，返回的是结果，不是哈希对象。确保你只在哈希对象上调用 update() 和 digest() (且 digest 只调用一次)。
区分同步和异步方法: 对于 pbkdf2 和 scrypt 等异步方法，确保使用回调或 Promise 来获取结果。
查阅文档: 当不确定某个方法应该在哪个对象上调用，或者它的返回值是什么类型时，查阅 Node.js 官方 crypto 模块文档是最好的方法。

第七章：哈希的最佳实践

选择合适的算法: 对于通用数据完整性检查，SHA-256 或 SHA-512 是不错的选择。切勿在安全敏感的场景（如密码存储）使用 MD5 或 SHA-1。
密码存储使用 KDFs: 始终使用 PBKDF2、Scrypt 或 bcrypt (第三方库) 来哈希密码，并结合随机、唯一的盐值。
使用足够的迭代次数/成本因子: KDFs 的强度参数需要根据你的硬件能力进行测试和调整，确保计算时间在可接受的范围内（例如，用户登录验证在几百毫秒内完成），同时提供足够的安全性。随着时间推移和计算能力的增强，可能需要增加这些参数。
为密码存储生成随机盐值: 每个密码都应该有自己唯一的、随机生成的盐值。将盐值与哈希后的密码一起存储。
使用 crypto.randomBytes() 生成盐值: 不要使用不安全的随机数生成器。
使用 timingSafeEqual() 比较哈希值: 避免时序攻击。
处理大文件/数据流时使用 update() 分块: 避免一次性加载大量数据到内存。
注意字符串编码: 在调用 update() 时，如果输入是字符串，建议明确指定编码（如 ‘utf8’），以避免潜在的问题。
错误处理: 在进行加密操作时，始终考虑可能的错误（如算法不支持、输入无效等），并使用 try...catch 或检查回调函数的错误参数进行处理。

第八章：总结

Node.js 的 crypto 模块为我们提供了强大的哈希功能，是构建安全应用的重要工具。掌握 crypto.createHash(), crypto.createHmac(), crypto.scrypt() / crypto.pbkdf2() 这些方法是关键。

本文详细介绍了这些方法的用法，并通过示例代码进行了说明。更重要的是，我们深入分析了导致 “TypeError: … is not a function” 这个常见错误的原因，主要包括在 digest() 结果上调用方法、变量未正确初始化、方法名拼写错误以及异步方法使用不当。通过理解这些错误发生的上下文和调试策略，你可以更有效地定位并解决问题。

遵循本文提出的最佳实践，如选择合适的算法、对密码使用 KDFs 并加盐、使用 timingSafeEqual() 进行比较等，将帮助你构建更安全可靠的 Node.js 应用。希望这篇详细指南能够帮助你更好地理解和使用 Node.js crypto 模块的哈希功能，顺利解决开发中遇到的问题。

Node.js crypto 模块哈希用法深度解析：告别 “is not a function” 错误

第一章：理解哈希（Hashing）的基本概念

第二章：Node.js crypto 模块入门

第三章：使用 crypto.createHash() 进行基本哈希

第四章：使用 crypto.createHmac() 进行带密钥的哈希 (HMAC)

第五章：密码哈希 (使用 PBKDF2 或 Scrypt)

第六章：解决 “TypeError: … is not a function” 错误

第七章：哈希的最佳实践

第八章：总结

发表评论 取消回复

Node.js `crypto` 模块哈希用法深度解析：告别 “is not a function” 错误

第二章：Node.js `crypto` 模块入门

第三章：使用 `crypto.createHash()` 进行基本哈希

第四章：使用 `crypto.createHmac()` 进行带密钥的哈希 (HMAC)

发表评论取消回复