APCU前缀隔离必须手动配apcu-prefix，因APCU默认不区分项目缓存，多应用共享时类映射会互相覆盖；该配置需在composer.json的config字段中声明，支持{DOCUMENT_ROOT}等变量插值，且须执行dump-autoload生效。
APCU 前缀隔离为什么必须手动配 apcu-prefix
APCU 默认不隔离不同 Composer 项目缓存，多个应用共用同一份 opcode + 用户缓存时，composer autoload 生成的类映射会互相覆盖，导致「类找不到」或「加载了旧版本类」。这不是 APCU 的 bug，而是它设计上就靠前缀区分作用域——Composer 不自动设，就得你来填。
关键点：只有启用 apcu 且多个项目共享同一个 PHP-FPM 进程池（或 CLI 共享 APCU 实例）时，这问题才暴露；单项目基本无感。
-
apcu.enabled=1和apcu.shm_size需已开启并足够大（建议 ≥64M） - PHP 版本 ≥7.4（
apcu_prefix在 7.4+ 支持变量插值，更安全） - 前缀必须全局唯一，推荐用项目根目录哈希或
$_SERVER['DOCUMENT_ROOT']衍生值
怎么在 composer.json 里正确写 apcu-prefix
这个配置不是写在 PHP ini 里，也不是运行时 set，而是通过 Composer 自身的 config 字段声明，由 composer dump-autoload 注入到生成的 autoload 文件中。
错误写法："apcu-prefix": "myapp" —— 静态字符串在多租环境必然冲突；正确做法是让 Composer 自动推导路径哈希：
"config": {
"apcu-prefix": "composer-{$HOME}-"
}
但注意：{$HOME} 只在 CLI 下可靠；Web 环境常用 {DOCUMENT_ROOT} 或 {PWD}，前提是 PHP 启用了 apc.stat=0 且 apc.use_request_time=1（否则变量不解析）。
- 实际生效依赖
composer install或dump-autoload -o重生成vendor/autoload.php - 验证是否写入：打开
vendor/composer/autoload_real.php，搜apcu_fetch，看 key 是否含你设的前缀 - 若用 Docker，
{PWD}可能是容器内路径，需确保各租户挂载路径不同
apcu-prefix 生效但类仍加载错？检查这三个地方
前缀写了、dump 了、APCU 也开了，还是报 Class not found —— 大概率是缓存没清干净或前缀没真正参与 autoload 流程。
- 先执行
php -r "apcu_clear_cache('user');"清空用户缓存（opcode 缓存不用清） - 确认
vendor/autoload.php加载的是你当前项目的，不是被 symlink 到公共目录的旧副本 - 检查是否启用了
composer config --global apcu-prefix，全局配置会覆盖项目级配置，用composer config --list查 - Apache + mod_php 下，
{DOCUMENT_ROOT}是可靠的；Nginx + PHP-FPM 下，得确保fastcgi_param SCRIPT_FILENAME正确传递，否则{DOCUMENT_ROOT}解析为空
多租环境下前缀长度和性能影响
APCU 键名过长会影响哈希查找速度，但实际中只要别堆砌时间戳/随机数，几十字符完全没问题。重点不在长度，而在「唯一性 + 稳定性」。
常见翻车点："apcu-prefix": "myapp-{time()}" —— 每次 dump 都变，导致缓存彻底失效；或者用 {$_ENV['APP_ID']} 但没在 FPM pool env 中透传。
- 推荐方案：
"apcu-prefix": "composer-".hash("crc32b", __DIR__)."-"（写进autoload_files.php更稳妥，但需自定义 autoloader） - 更省事：直接用项目 basename，如
"apcu-prefix": "myproject-"，前提是部署时目录名严格隔离（CI/CD 控制） - APCU 用户缓存命中率下降 5–10% 属正常，别为了“极致命中”牺牲隔离性
最麻烦的从来不是怎么配，而是配完忘了告诉运维——APCU 缓存跨进程不共享，FPM 子进程重启后前缀一致就行，但如果你用的是 serverless 或短命容器，每次冷启都得重新 dump，这时候前缀稳定性比性能更重要。
