Private Packagist 配置需同时完成全局 token 注册与项目级 repository 声明，缺一不可；token 决定包访问权限，必须通过 composer config -g http-basic.repo.packagist.com TOKEN "" 设置，且 repositories 中需明确声明私有源 URL。
Private Packagist 的 Composer 配置需要 token 和 repository 声明
Private Packagist 不是简单改 composer.json 里的 repositories 就能用的，必须绑定企业账户生成的访问 token。这个 token 决定你能拉哪些包、是否能安装私有依赖、有没有写权限。
配置分两步：全局凭证注册 + 项目级源声明。漏掉任一环节都会报 Could not fetch https://repo.packagist.com/your-org/... 或 401 Unauthorized。
- 先在 Private Packagist 后台「API Tokens」页生成一个
read（或read-write）token，复制下来 - 运行
composer config -g http-basic.repo.packagist.com your-token ""（注意密码字段留空，Private Packagist 只认用户名位置传 token） - 在项目
composer.json的repositories里加一条："packagist": false, "private-packagist": { "type": "composer", "url": "https://repo.packagist.com/your-org/" }
为什么不能只靠 auth.json 手动写？
手动维护 auth.json 看似省事，但在 CI/CD 或多团队协作中容易出问题：token 权限变更后本地文件不同步、误提交到 Git、不同环境 token 不一致导致部分机器装包失败。
推荐用 composer config -g 注册全局凭证，因为：
- Composer 会自动把 token 加进每次请求的
Authorization: Basic ...头里，和 Private Packagist 期望格式完全匹配 - CI 环境可通过
COMPOSER_AUTH环境变量注入（值为 JSON 字符串：{"http-basic":{"repo.packagist.com":{"username":"TOKEN","password":""}}}） - 避免在项目根目录下硬编码敏感信息
composer install 报 package not found 的常见原因
即使 token 和源都配对了，仍可能提示找不到包，本质是 Private Packagist 的包可见性控制比 Packagist.org 严格得多。
- 确认该包已明确添加到你的 Private Packagist 组织的「Packages」列表中（不是仅在 GitHub/GitLab 连接里出现就算）
- 检查包名是否拼错 —— Private Packagist 区分大小写，且不支持通配符自动发现
- 如果包是私有 Git 仓库（比如
git@github.com:org/private-lib.git），需在 Private Packagist 后台手动 sync，并勾选「Include in composer repository」 -
composer clear-cache之后再试，旧缓存可能残留 404 响应
企业级部署要注意的兼容性细节
Private Packagist 默认启用「Package signing」和「Repository mirroring」，但这些功能会影响 Composer 行为：
- 开启签名后，
composer install会校验packages.json的 GPG 签名，若本地没导入对应公钥，会直接中断 —— 需提前运行composer config -g repo.packagist.com.gpg-key /path/to/key.asc - 镜像模式下，
packagist.org的包会被自动代理，但如果你显式禁用了默认源（"packagist": false），又没把packagist.org加进repositories，就会连monolog/monolog这类公共包也装不了 - PHP 版本约束要和 Private Packagist 后台设置的「Minimum PHP version」一致，否则包虽存在，也会被过滤掉
最常被忽略的是组织域名拼写 —— repo.packagist.com/your-org 中的 your-org 必须和后台 URL 完全一致（含短横线、大小写），少一个字符就 404。
