如何使用 hash_update_stream 函数安全地对上传文件进行哈希校验？

M66 2025-06-23

在进行文件上传操作时，确保文件的完整性与安全性是非常重要的一步。为了验证文件在上传过程中是否被篡改，我们可以使用哈希校验。PHP 提供了 hash_update_stream 函数，可以高效地对大型文件进行哈希校验。

本文将详细介绍如何使用 hash_update_stream 函数进行文件的哈希校验，并确保文件的安全性。

1. 什么是 hash_update_stream 函数？

hash_update_stream 是 PHP 内置的哈希函数，它能够实时地处理一个流（如文件流），并对其进行哈希运算。相较于一次性加载整个文件进行哈希校验，hash_update_stream 函数能够节省内存资源，适用于大文件的校验。

函数签名如下：

bool hash_update_stream ( resource $context , resource $file )

$context: 哈希上下文资源，由 hash_init 函数创建。
$file: 文件资源，通常是通过 fopen 函数打开的文件流。

2. 使用 hash_update_stream 对上传文件进行哈希校验

2.1 上传文件的基本处理

在上传文件时，通常会使用 $_FILES 超全局数组来获取文件信息。在进行哈希校验之前，我们需要先检查文件是否有效并进行处理。

以下是一个上传文件的基本示例：

if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['file'])) {
    $file = $_FILES['file'];
    
    // 检查文件是否上传成功
    if ($file['error'] === UPLOAD_ERR_OK) {
        $filePath = $file['tmp_name']; // 临时文件路径
        $fileName = $file['name'];
        
        // 执行哈希校验
        if (checkFileHash($filePath)) {
            echo "文件哈希校验成功，文件安全。";
        } else {
            echo "文件哈希校验失败，文件可能已被篡改。";
        }
    } else {
        echo "文件上传失败，错误代码：" . $file['error'];
    }
}

2.2 使用 hash_update_stream 进行文件哈希校验

接下来，我们编写一个 checkFileHash 函数，使用 hash_update_stream 函数对上传的文件进行哈希计算。

function checkFileHash($filePath) {
    // 创建一个SHA256哈希上下文
    $hashContext = hash_init('sha256');

    // 打开文件流
    $fileStream = fopen($filePath, 'rb');
    if ($fileStream === false) {
        return false; // 无法打开文件流
    }

    // 使用 hash_update_stream 对文件流进行哈希计算
    if (hash_update_stream($hashContext, $fileStream)) {
        // 获取最终的哈希值
        $fileHash = hash_final($hashContext);
        fclose($fileStream);

        // 你可以将哈希值与预期值进行比较，确保文件没有被篡改
        // 这里的示例值 `预期哈希值` 为示例，你需要替换成实际的正确哈希值
        $expectedHash = '预期哈希值';
        return $fileHash === $expectedHash;
    }

    fclose($fileStream);
    return false; // 哈希计算失败
}

2.3 为什么要使用 hash_update_stream？

hash_update_stream 函数的主要优势在于它能够处理流数据，不需要将整个文件加载到内存中。对于大文件来说，使用 hash_update_stream 比一次性加载整个文件并计算哈希要更加高效，尤其是在内存资源有限的环境下。

3. 总结

使用 hash_update_stream 函数对上传文件进行哈希校验，不仅能够有效防止文件在上传过程中被篡改，还能够处理大文件，避免占用过多内存。通过结合文件的哈希值与预期值的对比，我们能够验证文件的完整性，从而提高系统的安全性。

在实际应用中，你可以根据需要选择不同的哈希算法（如 sha256、md5 等）来进行文件验证。