直接执行 composer require ramsey/uuid 即可安装，PHP≥7.2 且 Composer 2.x 无需额外配置；需手动引入 vendor/autoload.php，否则报类未找到；uuid4 推荐用于大多数场景，SQL 中须用参数绑定而非字符串拼接。
直接执行 composer require ramsey/uuid 就够了
绝大多数现代 PHP 项目（PHP >= 7.2，Composer 2.x）无需额外配置即可安装。Ramsey UUID 库已完全迁移到 PSR-4 自动加载，且无硬依赖扩展（ext-uuid 是可选的，不装也不报错）。运行命令后，Composer 会自动写入 composer.json 并生成对应 autoload 规则。
常见错误现象：Could not find package ramsey/uuid —— 基本是 Composer 源被墙或配置了私有镜像但未同步该包；ramsey/uuid requires php ^7.2 || ^8.0 —— 说明当前 PHP 版本低于 7.2，需升级 PHP 或降级使用 ramsey/uuid:^3.9（仅限 PHP 5.6+，但已停止维护，不推荐）。
安装后必须手动 require vendor/autoload.php
不同于某些框架自动引入 autoloader，纯 Composer 项目中，只要没用框架（如 Laravel、Symfony），就必须在入口文件（如 index.php 或测试脚本）顶部显式加载：
require 'vendor/autoload.php';
漏掉这行，调用 Uuid::uuid4() 会直接报 Class 'Ramsey\Uuid\Uuid' not found。这不是库的问题，是 PSR-4 加载机制的基本前提。
使用场景：CLI 脚本、简单 Web 入口、单元测试启动文件 —— 都要检查这一行是否存在。IDE 可能不报错（因有 stub 或 psalm/phpstan 支持），但运行时一定失败。
ramsey/uuid-doctrine 是可选插件，不是主库的一部分
如果你在 Doctrine 实体里想直接用 Uuid 类型映射数据库字段，才需要额外安装：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
composer require ramsey/uuid-doctrine
它不参与 UUID 生成逻辑，只提供 Doctrine 的类型绑定和转换器。主库 ramsey/uuid 本身不含任何 ORM 相关代码。
参数差异注意点：
-
Uuid::uuid4()生成随机 UUID（推荐用于大多数场景） -
Uuid::uuid1()依赖系统时间戳 + MAC 地址，多容器/云环境可能重复（MAC 不唯一） -
Uuid::uuid6()（v6）需ramsey/uuid:^4.7，不是所有旧项目都支持，别盲目替换
生成 UUID 后不要用 __toString() 拼 SQL 字符串
虽然 $uuid->toString() 或强制转字符串（(string) $uuid）能拿到标准格式（如 550e8400-e29b-41d4-a716-446655440000），但在 PDO/MySQL 中直接拼进 SQL 容易触发注入或类型隐式转换问题。
正确做法始终用参数绑定：
$stmt = $pdo->prepare('INSERT INTO users (id, name) VALUES (?, ?)');
$stmt->execute([(string) $uuid, 'Alice']);
性能影响：UUID 字符串长度固定（36 字符），比自增整数主键略占空间、索引效率稍低，但这是业务权衡，不是安装环节的问题。
容易被忽略的地方：有些团队把 UUID 当作“更安全的 ID”就以为可以裸露在 URL 或 API 返回里，其实 v4 UUID 仍可被枚举（只是概率极低），敏感接口仍需权限校验，不能靠 UUID 格式本身防越权。
