xmake-docs/docs/zh/api/scripts/builtin-modules/hash.md

hash

hash 模块提供了哈希值计算和 UUID 生成功能，这是 xmake 的一个内置模块。

hash.md5

• 计算文件或二进制数据的 MD5 哈希值

函数原型

::: tip API

hash.md5(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据
• 常见错误：如果文件不存在，函数会错误地将文件路径作为字符串数据来计算哈希值，且不会报错，导致结果不正确 :::

用法说明

计算指定文件或二进制数据的 MD5 哈希值，返回十六进制格式的哈希字符串。

计算文件哈希值：

-- 计算文件的 MD5 哈希值
local checksum = hash.md5("/path/to/file.txt")
print("MD5: " .. checksum)

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 MD5 哈希值
local data = bytes("hello")
local checksum = hash.md5(data)
print("MD5: " .. checksum)

错误用法（不要这样做）：

-- ❌ 错误：如果 "hello" 不是文件路径，会错误地计算文件路径字符串的哈希值
local checksum = hash.md5("hello")

-- ✅ 正确：使用 bytes 包装二进制数据
local checksum = hash.md5(bytes("hello"))

hash.sha1

• 计算文件或二进制数据的 SHA1 哈希值

函数原型

::: tip API

hash.sha1(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据 :::

用法说明

计算指定文件或二进制数据的 SHA1 哈希值，返回十六进制格式的哈希字符串。

计算文件哈希值：

-- 计算文件的 SHA1 哈希值
local checksum = hash.sha1("/path/to/file.txt")

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 SHA1 哈希值
local checksum = hash.sha1(bytes("hello"))

hash.sha256

• 计算文件或二进制数据的 SHA256 哈希值

函数原型

::: tip API

hash.sha256(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据 :::

用法说明

计算指定文件或二进制数据的 SHA256 哈希值，返回十六进制格式的哈希字符串。

SHA256 比 MD5 更安全，常用于包的完整性校验：

计算文件哈希值：

-- 校验下载的包文件
local packagefile = "package.tar.gz"
local checksum = hash.sha256(packagefile)
if checksum ~= expected_hash then
    raise("checksum mismatch!")
end

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 SHA256 哈希值
local checksum = hash.sha256(bytes("hello"))

hash.uuid

• 根据名称生成 UUID

函数原型

::: tip API

hash.uuid(name: <string>)

:::

参数说明

参数	描述
name	名称字符串

用法说明

根据给定的名称字符串生成一个确定性的 UUID，相同的名称总是生成相同的 UUID。

内部调用 hash.uuid4(str)，格式为：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

适合为特定配置生成固定的唯一标识符：

-- 为不同的编译配置生成确定性 ID
local config_id = hash.uuid("debug-x64-windows")

hash.xxhash32

• 计算文件或二进制数据的 32 位 xxHash 哈希值

函数原型

::: tip API

hash.xxhash32(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据 :::

用法说明

使用 xxHash32 算法计算文件或二进制数据的哈希值，xxHash 是一个极快的非加密哈希算法，适合用于哈希表、校验和等场景。

计算文件哈希值：

-- 计算文件的 xxHash32 哈希值
local checksum = hash.xxhash32("/path/to/file.txt")

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 xxHash32 哈希值
local checksum = hash.xxhash32(bytes("hello"))

hash.xxhash64

• 计算文件或二进制数据的 64 位 xxHash 哈希值

函数原型

::: tip API

hash.xxhash64(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据 :::

用法说明

使用 xxHash64 算法计算文件或二进制数据的哈希值，速度快，适合快速校验。

计算文件哈希值：

-- 计算文件的 xxHash64 哈希值
local checksum = hash.xxhash64("/path/to/file.txt")

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 xxHash64 哈希值
local checksum = hash.xxhash64(bytes("hello"))

错误用法（不要这样做）：

-- ❌ 错误：不要直接传入字符串数据
local key = hash.xxhash64(table.concat(params, "|"))

-- ✅ 正确：使用 bytes 包装二进制数据
local key = hash.xxhash64(bytes(table.concat(params, "|")))

hash.xxhash128

• 计算文件或二进制数据的 128 位 xxHash 哈希值

函数原型

::: tip API

hash.xxhash128(input: <string|bytes>)

:::

参数说明

参数	描述
input	文件路径（string）或二进制数据（bytes）

::: warning 重要提示

• string 参数只能作为文件路径传入：如果传入的字符串是文件路径，函数会计算该文件的哈希值
• 二进制数据必须使用 bytes 参数：要计算二进制数据的哈希值，必须使用 bytes() 函数包装数据 :::

用法说明

使用 xxHash128 算法计算文件或二进制数据的哈希值，提供更长的哈希值以减少冲突。

计算文件哈希值：

-- 计算文件的 xxHash128 哈希值
local checksum = hash.xxhash128("/path/to/file.txt")

计算二进制数据哈希值：

import("core.base.bytes")

-- 计算二进制数据的 xxHash128 哈希值
local checksum = hash.xxhash128(bytes("hello"))

hash.strhash32

• 从字符串生成 32 位哈希值

函数原型

::: tip API

hash.strhash32(input: <string>)

:::

参数说明

参数	描述
input	字符串

用法说明

从字符串生成 32 位哈希值，返回格式如：91e8ecf1

这个接口内部使用 xxhash32，专门用于字符串快速哈希。

hash.strhash64

• 从字符串生成 64 位哈希值

函数原型

::: tip API

hash.strhash64(input: <string>)

:::

参数说明

参数	描述
input	字符串

用法说明

从字符串生成 64 位哈希值，返回格式如：91e8ecf191e8ecf1

hash.strhash128

• 从字符串生成 128 位哈希值

函数原型

::: tip API

hash.strhash128(input: <string>)

:::

参数说明

参数	描述
input	字符串

用法说明

从字符串生成 128 位哈希值，返回格式如：91e8ecf1417f4edfa574e22d7d8d204a

适合用于生成编译缓存键：

-- 为编译缓存生成键
local cache_key = hash.strhash128(compiler .. flags .. source)

hash.rand32

• 生成 32 位随机哈希值

函数原型

::: tip API

hash.rand32()

:::

参数说明

此函数不需要参数。

用法说明

生成一个 32 位的随机哈希值。

::: warning 注意 此接口容易触发哈希冲突，不建议用于需要高唯一性的场景。 :::

hash.rand64

• 生成 64 位随机哈希值

函数原型

::: tip API

hash.rand64()

:::

参数说明

此函数不需要参数。

用法说明

生成一个 64 位的随机哈希值。

hash.rand128

• 生成 128 位随机哈希值

函数原型

::: tip API

hash.rand128()

:::

参数说明

此函数不需要参数。

用法说明

生成一个 128 位的随机哈希值。