私有仓库配置需显式禁用 packagist.org 并正确设置 repositories 和 auth.json：url 末尾必须带斜杠，"packagist.org": false 为布尔值；gitlab 用 gitlab-token，镜像用 http-basic，ci/cd 用 composer_auth；vcs 包 require 必须加 dev- 前缀；上线前须验证 packages.json 可访问、url 一致、私有包 name 正确且不冲突。
私有仓库 URL 配置必须显式禁用 packagist.org
不关掉默认源，哪怕 repositories 里写了正确的私有地址，composer install 也会优先去 packagist.org 查——查不到才 fallback，但 fallback 不会匹配私有包名（因为命名空间冲突或元数据缺失），最终报 Could not find package vendor/name。
必须在项目级 composer.json 中写死这一行：
{
"repositories": [
{
"type": "composer",
"url": "https://repo.example.com/"
}
],
"packagist.org": false
}
-
url末尾的斜杠/不可省，少一个就 404 -
"packagist.org": false是布尔值，不是字符串，不能加引号 - 如果团队共用同一套私有仓库，建议把这行写进脚手架模板，避免每个项目手动补
auth.json 认证方式要按场景选对位置和字段
凭证放错地方，composer update 就会卡在 401 或 403；放对了但字段名写错，比如把 gitlab-token 写成 gitlab-oauth，照样失败。
三种典型场景对应不同写法：
- GitLab 私有仓库（vcs 类型）：用
gitlab-token字段，值是glpat-xxx，域名必须和 GitLab 实例地址完全一致（如gitlab.example.com） - 私有 Packagist 镜像（composer 类型）：用
http-basic，password字段填 API token（很多 Satis/Artifactory 实现把它当密码用） - CI/CD 环境：别放文件，改用
COMPOSER_AUTH环境变量，避免凭据落盘
注意：auth.json 必须加进 .gitignore；全局配置走 composer config --global，项目级配置优先级更高，适合多团队混用同一台开发机的情况。
VCS 类型仓库 require 时必须带 dev- 前缀或稳定版本号
直接 composer require vendor/package 会失败，因为 Composer 默认只认稳定版（stable），而 VCS 源里的分支（如 main、develop）没有打 tag，会被当成 dev-main，需显式声明。
- 命令行安装：用
composer require vendor/package:dev-main - 手动写
composer.json："require": { "vendor/package": "dev-main" } - 若已打 tag（如
v1.2.0），可写"^1.2"，但前提是该 tag 下的composer.json里name和version字段正确且匹配
漏掉 dev- 前缀是最常见的“包存在却装不上”原因，错误信息通常是 Could not find a version of vendor/package matching...，而不是权限类报错。
Satis/Artifactory 仓库上线前必做三件事
Satis 生成的是静态文件，Artifactory 是动态服务，但两者上线后都容易因链路断点导致客户端完全感知不到私有源。
- 先用
curl -I https://satis.example.com/packages.json确认能返回 200，Nginx/Apache 权限配错会导致静默 fallback 到 packagist.org - 检查项目
composer.json里的url是否和curl地址完全一致（协议、域名、路径、结尾斜杠） - 私有包自己的
composer.json必须含name字段，格式为vendor/package，且不能和 packagist.org 上已有包重名，否则 Composer 会拒绝解析
跨团队协作最麻烦的不是搭建，而是各环节配置散落在不同人手里——URL 在运维那，token 在安全组那，name 在开发者那。建议把这三项做成 checklist，每次新包上线前过一遍。
