直接运行 composer require ramsey/uuid 即可安装支持 PHP 8.0–8.3 的纯 PHP 实现版本（v4.7+），无需 ext-uuid；需引入 vendor/autoload.php，错误“Class not found”多因未加载自动加载文件。

用 Composer 安装 ramsey/uuid 最简流程

直接运行 composer require ramsey/uuid 即可安装当前稳定版（v4.7+），它已全面支持 PHP 8.0–8.3，且不依赖 ext-uuid 扩展——纯 PHP 实现，无额外扩展要求。

常见错误：Class 'Ramsey\Uuid\Uuid' not found 多因未引入自动加载文件，确认项目根目录下执行命令，且后续 PHP 脚本开头包含 require 'vendor/autoload.php';。

• 若项目已禁用 Packagist 镜像，需先配置国内源：composer config -g repo.packagist https://packagist.phpcomposer.com（或使用阿里云源）
• 如遇 ext-gmp missing 报错，说明系统缺少 GMP 扩展，Ubuntu/Debian 下运行 sudo apt-get install php-gmp，CentOS/RHEL 用 yum install php-gmp
• 旧项目 PHP 版本低于 7.4？请锁定 v3.x：composer require ramsey/uuid:^3.9（但 v3 不支持 UUID v6/v7）

生成不同版本 UUID 的写法差异

v4（随机）、v1（时间+MAC）、v5（SHA1 命名）等版本生成方式不同，核心是调用对应工厂方法，不是靠参数开关。

示例：

use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidFactory;

// 默认生成 v4（最常用）
$uuid = Uuid::uuid4();

// 生成 v1（含时间戳和节点信息，需系统有 MAC 地址或手动提供）
$uuid = Uuid::uuid1();

// 生成 v5（基于命名空间 + 字符串，确定性哈希）
$ns = Uuid::uuid4(); // 命名空间本身也是 UUID
$uuid = Uuid::uuid5($ns, 'user@example.com');

// 如需 v6（有序时间优先），需显式使用工厂（v4.7+ 支持）
$factory = new UuidFactory();
$uuid = $factory->uuid6();

• v1 在容器或无网络接口环境可能 fallback 到随机生成，行为不可控，生产环境慎用
• v5 和 v3 都是命名型，但 v5 用 SHA1、v3 用 MD5；MD5 已不推荐，v3 库仍存在但不建议新项目选用
• v6/v7 是较新标准（RFC 9562），需确保 ramsey/uuid ≥ 4.7 且明确调用 uuid6() 或 uuid7()，不能靠字符串参数推断

转字符串、校验、解析的实用操作

生成后通常要存数据库或传 API，必须转成字符串；反向解析则用于验证或提取时间戳（v1/v6/v7）。

关键点：

• 所有 Uuid 对象都实现了 __toString()，直接 (string) $uuid 或 $uuid->toString() 即可获得小写 32 位十六进制格式（如 6ba7b810-9dad-11d1-80b4-00c04fd430c8）
• 校验字符串是否为合法 UUID：用 Uuid::isValid('...')，它能识别带花括号、大写、无连字符等多种格式，但不校验版本
• 从字符串重建对象：$uuid = Uuid::fromString('...');，失败时抛 InvalidArgumentException，建议 try/catch
• v6/v7 可提取时间：$uuid->getDateTime() 返回 DateTimeImmutable，v1 同理；v4/v5 返回 null

性能与存储注意事项

UUID 字符串长度固定 36 字符（含连字符），若存 MySQL，别用 VARCHAR(36)——索引效率低。更优方案：

• MySQL 中存为 BINARY(16)：用 $uuid->getBytes() 获取 16 字节原始数据，查询时用 UNHEX(REPLACE(uuid_str, '-', '')) 插入
• Laravel 用户可直接用 uuid 类型迁移字段，Eloquent 自动处理序列化
• PostgreSQL 原生支持 UUID 类型，直接存字符串即可，索引效率接近 CHAR(36)
• 高并发下 v4 性能足够，但若需时间有序（如分库分表排序），优先选 v6/v7，避免 v1 的 MAC 依赖和时钟回拨风险

真正容易被忽略的是字节序处理：从 getBytes() 得到的是网络字节序（big-endian），某些 C 扩展或底层存储可能默认小端，跨语言对接时务必确认一致性。