Composer install 报“Could not find package”是因为默认仅查询 packagist.org，私有包（如 acme/utils）未配置 repositories 源则无法定位；必须在 composer.json 中显式声明可访问的 vcs 或 composer 类型源，且 URL 需合法、以 / 结尾（Satis 等场景），否则静默失败。
为什么 composer install 会报 “Could not find package”
因为 Composer 默认只查 packagist.org，而私有包（比如 acme/utils）根本不在那里。它不会自动“猜”你有私有源，也不会 fallback 到本地 Git 或 Satis 目录——直接失败。
常见错误现象：
– 执行 composer install 报错 Could not find package acme/utils
– composer require acme/utils 卡住几秒后同样报错
– composer diagnose 显示一切正常，但就是拉不到包
- 必须显式声明源：要么改全局配置，要么在项目
composer.json的repositories字段里加一条 - 不能只写包名，得告诉 Composer “去哪找”，URL 必须可访问且返回合法的
packages.json - 如果用的是 Satis，注意它不提供服务，只是生成静态文件；你得用 Nginx/Apache 托管那个目录，且 URL 必须以
/结尾（否则拼出//packages.json）
如何正确配置阿里云镜像（避免静默回退）
很多人配完 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，发现还是慢、还是走官方源——大概率是 URL 少了末尾斜杠，或被项目级配置覆盖了。
- 验证是否生效：
composer config -g repo.packagist输出必须是完整 JSON，形如{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}（注意结尾/） - 项目级配置会全量替换
repositories字段，不是“追加”。如果项目已有私有 Git 源，执行该命令后那些源就丢了 - ECS 用户优先用内网地址：
http://mirrors.cloud.aliyuncs.com/composer/（无 HTTPS，仅限阿里云内网） - 临时绕过所有配置验证源可用性：
composer require phpunit/phpunit -r https://mirrors.aliyun.com/composer/
satis.json 中 require 和 archive 的关键写法
Satis 构建失败、漏包、composer install --prefer-dist 仍走 Git 而非 ZIP，八成卡在这两处。
-
require必须写具体包名 + 版本约束，不支持通配符：
✅"acme/utils": "dev-main"
❌"acme/*": "*"（Satis 不解析 glob） - 要生成 ZIP 包供离线部署，必须启用
archive块："archive": { "directory": "dist", "format": "zip", "skip-dev": true }
否则--prefer-dist会退化为--prefer-source - 私有 Git 仓库需提前配好 SSH key 或 HTTPS token；Satis clone 失败时静默跳过，不报错也不提示，容易误以为“包没写进 satis.json”
全局配置在 CI/宝塔等环境为何不生效
composer config -g 写的是当前用户的 ~/.composer/config.json。但在 Jenkins、宝塔面板、systemd 服务里，真正跑 composer install 的用户往往是 www、jenkins 或 root，而不是你登录 shell 的账号。
- CI 场景下，应在 pipeline 开头显式运行配置命令，且确保以目标用户身份执行
- 宝塔中 PHP 项目使用 Composer，需在“PHP 设置 → 环境变量”里确认
COMPOSER_HOME指向正确路径，或直接在脚本里用-d COMPOSER_HOME=/www/wwwroot/xxx/.composer - 已有
composer.lock的项目首次切新镜像，常因 hash 不匹配失败；稳妥做法是删掉vendor和composer.lock后重装
最易被忽略的一点：项目 composer.json 里只要存在 repositories 字段，无论内容是否为空，都会让全局 repo.packagist 配置彻底失效——这个逻辑没有警告，也没有日志，只能靠手动检查。
