“Package not found”错误常因权限不足导致Composer无法读取vendor/composer/installed.json或缓存文件，误判为包不存在；应先用ls -ld和composer show验证归属权，再sudo chown修复vendor/与缓存目录所有权，最后执行composer install --no-scripts重建元数据。
根本不是包不存在，而是权限错误被 Composer 误判为“Package not found”——典型现象是 composer require 或 composer install 报 Could not find package xxx/yyy，但 composer search xxx/yyy 能搜到，且 Packagist 页面也显示包存在。
为什么权限问题会触发“package not found”错误
Composer 在解析依赖时，若因权限不足无法读取 vendor/composer/installed.json、composer.lock 或缓存目录下的元数据文件，会静默跳过本地已安装信息，转而尝试从远程源重新解析整个依赖树。一旦此时又因权限问题无法写入临时缓存（如 ~/.composer/cache/），它就会提前中止解析流程，并把失败归因为“找不到包”，而非抛出真实的 Permission denied。
- 常见诱因：之前用
sudo composer install污染了vendor/或~/.composer/cache/，导致当前用户无法读取已安装包的元数据 - 关键线索：错误前有
Warning: file_get_contents(.../installed.json): failed to open stream: Permission denied（常被 -q 参数掩盖） - 验证方式：手动运行
cat vendor/composer/installed.json 2>/dev/null || echo "read failed"，若失败即确认权限阻断
快速定位是否为权限误报
别急着换镜像或重装 Composer，先用三行命令交叉验证：
-
ls -ld vendor/ composer.lock $(composer config --global cache-dir)—— 任意一行第三列不是$(whoami)，就说明归属错配 -
composer show --all 2>/dev/null | head -n1 || echo "show failed — likely permission block"—— 若直接报错或无输出，基本坐实权限链断裂 -
composer diagnose --verbose 2>&1 | grep -i "permission\|cache\|installed"—— 查看诊断日志里是否有真实权限拒绝痕迹
修复顺序必须严格：先归还所有权，再验证元数据
chown 是唯一该用 sudo 的环节；chmod 和删文件都是次要动作，且仅在 chown 后仍异常时才考虑：
- 项目级修复：
sudo chown -R $USER:$USER vendor/ composer.lock（注意不加末尾/，否则composer.lock文件本身可能漏掉） - 全局缓存修复：
sudo chown -R $USER:$USER $(composer config --global cache-dir) - 完成后立刻验证：
composer show laravel/framework—— 若能正常输出版本列表，说明元数据读取已恢复；若仍报 not found，再检查composer.json中repositories配置是否生效 - 极端情况（如
vendor/composer/installed.json已损坏）：rm -f vendor/composer/installed.json && composer install --no-scripts，避免脚本执行再次触发权限失败
Docker / CI 场景下最容易忽略的 UID 错位
宿主机 UID 是 1000，容器内默认以 UID 0（root）运行并挂载 vendor/，会导致容器内进程能写，但宿主机用户无法读取生成的元数据文件——结果就是本地 composer show 失败，报“not found”。这不是镜像问题，是挂载权限映射缺失：
- Docker CLI 启动时加：
--user $(id -u):$(id -g) - Docker Compose 中写：
user: "${UID:-1000}:${GID:-1000}"（并在启动前export UID=$(id -u) GID=$(id -g)） - CI 脚本中不要复用本地
vendor/缓存，改用rm -rf vendor/ composer.lock后重新安装，或显式修复：sudo chown -R $(id -u):$(id -g) vendor/
最易被忽略的是：权限修复后，composer.lock 里的哈希值仍基于旧的、不可读的 installed.json，必须运行一次 composer update --lock 或至少 composer install --no-scripts 才能重建可信元数据。
