Ramsey UUID v4/v5 生成需匹配 PHP 版本（v4≥7.2，v5≥8.0），注意命名空间变更、自动加载、MySQL 字段类型与排序规则，Docker 中 uuid1 可能重复，推荐 uuid4 或 uuid6。
直接用 Ramsey\Uuid\Uuid::uuid4() 就能生成标准 UUID v4，但实际项目里容易卡在 autoload、版本兼容、或误用静态工厂方法上。
安装 Ramsey UUID 库时 Composer 报错 Class not found
常见于没执行自动加载，或用了旧版 PHP + 新版库。Ramsey UUID v4 要求 PHP >= 7.2，v5 要求 >= 8.0；v4 的命名空间是 Ramsey\Uuid\Uuid，v5 改为 Ramsey\Uuid\UuidFactory，混用会直接报错。
- 确认 PHP 版本：
php -v - 按版本装对应库：
composer require ramsey/uuid:^4.7（PHP 7.2–7.4）或composer require ramsey/uuid:^5.0（PHP 8.0+） - 确保已运行
composer dump-autoload，尤其在手动修改vendor/autoload.php后
生成 UUID 后存数据库失败：类型不匹配或截断
MySQL 的 CHAR(36) 或 UUID 类型（8.0+）能原生存 UUID 字符串，但很多人用 VARCHAR(36) 却忘了设 utf8mb4 排序规则——UUID 是 ASCII，虽不影响存储，但若字段默认是 utf8，某些旧驱动可能触发隐式转换警告。
- 推荐建表语句：
id CHAR(36) PRIMARY KEY，并显式指定COLLATE utf8mb4_bin - 避免用
UUID::uuid4()->toString()再拼接，直接用__toString()或jsonSerialize()输出字符串 - 若用 Laravel Eloquent，可在模型中加
protected $keyType = 'string'; public $incrementing = false;
想用 UUID v1（时间戳+MAC）但结果总一样
Uuid::uuid1() 依赖系统时间与网卡 MAC 地址，但在 Docker 容器、无网络环境或虚拟机里，MAC 可能固定为 00:00:00:00:00:00，导致多次调用返回相同 UUID（尤其测试环境下）。
立即学习“PHP免费学习笔记（深入）”；
- 生产环境务必验证
ifconfig或ip link是否有非 loopback 网卡 - 开发时可改用
Uuid::uuid4()，或传入自定义节点：Uuid::uuid1(null, null, new \Ramsey\Uuid\Codec\TimestampFirstCodec(), new \Ramsey\Uuid\Generator\CombGenerator()) - 更稳妥的做法：用
Uuid::uuid6()（v6 是时间优先的有序 UUID，需 v5.0+ 库）
真正麻烦的不是生成，而是跨服务、跨语言时 UUID 的二进制 vs 字符串表示——比如 PHP 用 toBytes() 存 binary(16)，Go 用 uuid.Must(uuid.Parse(...)) 解析字符串，中间少个 strtolower() 都可能校验失败。
