直接执行 composer require cache/cache 会失败，因为该包已从 Packagist 彻底下架；应改用 php-cache/adapter-common 及其具体适配器（如 filesystem-adapter），并注意正确传入依赖实例与判断缓存命中。
直接执行 composer require cache/cache 会失败
PHP-Cache 项目早已停止维护，官方推荐迁移到 php-cache/adapter-common 及其适配器（如 php-cache/filesystem-adapter），但很多人仍搜 “PHP-Cache” 就直接敲旧包名，结果报错：Could not find package cache/cache。这不是网络或 Composer 配置问题，是包已从 Packagist 彻底下架。
正确安装 PSR-6 兼容缓存组件的组合方式
PSR-6 的实现必须包含两部分：一个通用适配器（提供 PoolInterface） + 一个底层存储驱动（如文件、Redis）。现代标准做法是用 php-cache/adapter-common + 具体适配器：
-
composer require php-cache/adapter-common php-cache/filesystem-adapter—— 文件系统缓存（开发/测试常用） -
composer require php-cache/adapter-common php-cache/redis-adapter predis/predis—— Redis 缓存（需同时装predis/predis） -
composer require php-cache/adapter-common php-cache/apcu-adapter—— APCu（仅 CLI 或 Web SAPI 启用 APCu 时可用）
注意：php-cache/adapter-common 本身不提供存储能力，只是统一接口层；漏装具体适配器会导致 Class not found 错误。
实例化缓存 Pool 时别跳过适配器构造参数
常见错误是照抄文档片段却忽略依赖注入细节。例如文件缓存必须传入一个 Directory 实例，不能只 new 一个空类：
立即学习“PHP免费学习笔记（深入）”；
// ✅ 正确 use Cache\Adapter\Filesystem\FilesystemCachePool; use Cache\Adapter\Filesystem\Directory; $directory = new Directory(__DIR__ . '/cache'); $pool = new FilesystemCachePool($directory); // ❌ 错误：$directory 未初始化，会触发 TypeError $pool = new FilesystemCachePool(new Directory());
Redis 适配器同理，必须传入 Predis\Client 实例，不能只传 host/port 数组；APCu 适配器虽无参数，但需确认 apcu_enabled() 返回 true，否则写操作静默失败。
PSR-6 的 getItem() 和 save() 不是原子操作
很多开发者误以为调用 $pool->save($item) 就等于“写入成功”，其实它只返回布尔值，且不抛异常。更隐蔽的问题是：getItem() 返回的 CacheItemInterface 必须显式调用 isHit() 判断是否命中，而不是靠 get() 返回值真假：
-
null是合法缓存值（比如你存的就是null），所以不能用if (!$item->get())判定未命中 - 必须写成
if ($item->isHit()) { $data = $item->get(); } -
save()失败时返回false，但不会中断后续逻辑——建议加日志或断言
这个设计让 PSR-6 更严谨，但也更容易在迁移老代码时埋下空指针或缓存穿透隐患。
