Composer 遇到被占用的包名会直接报错且不自动降级或重试；必须确保 vendor 名与 GitHub/GitLab 组织名一致，package 名需加领域前缀避免冲突；私有包须禁用 packagist.org 并显式配置私有仓库。
Packagist 上包名被占用，Composer 会直接报错，不自动降级或重试
当你执行 composer require vendor/name 时，如果该 vendor/name 已被他人注册（哪怕只是空仓库），Composer 就会拒绝安装，并抛出明确错误：Could not find package vendor/name 或更具体的 Package vendor/name is not available。它不会尝试找近似名、旧版本或 fork，也不会提示“你是不是想用 xxx”。这是设计使然——Packagist 要求全局唯一性，Composer 完全依赖它做解析。
常见错误现象：本地写好 composer.json，composer install 却卡在「Resolving packages...」后失败；或者 CI 流水线突然崩了，日志里只有一行 Package not found，但你昨天还能装。
- 别指望 Composer 自动 fallback 到 GitHub/GitLab 直链——除非你手动加
repositories配置并设为packagist: false - 不要用公司域名倒写（如
com-example/mylib）当 vendor 名，Packagist 不校验域名所有权，但别人可能已占了com-example，且这种命名在 PHP 社区几乎没人认 - 如果你是团队内部包，又不想公开到 Packagist，必须显式配置私有仓库（
type: "composer"或"vcs"），否则 Composer 默认只查 Packagist
vendor 名必须真实对应组织/作者身份，不能纯造词或缩写
Packagist 强制要求 vendor 名与 GitHub/GitLab 用户名或组织名一致（通过 OAuth 绑定验证）。比如你在 GitHub 是 acme-inc，那只能用 acme-inc/package-name，不能用 acme/package-name 或 mycompany/package-name —— 后者即使没被占，提交时也会被拒绝。
使用场景：你想发布一个开源组件，但发现心仪 vendor 名已被注册（比如 utils、core、php 这类通用词早被抢光）。
- 优先用 GitHub 组织名，而不是个人用户名（避免人离职后包失控）
- 避免用项目代号、产品名作 vendor（如
firefly/mylib），等产品停更，这个 vendor 就废了 - 小团队没组织？老老实实用个人 GitHub ID，但提前想好是否长期维护；别用
dev-team这种模糊名——Packagist 不接受未绑定的 pseudo-vendor
package 名要带业务/领域前缀，避免和主流包撞名
就算 vendor 名是你自己的，package 名仍可能冲突。Packagist 不检查语义，只看字符串是否完全相同。例如你叫 myorg，想发个缓存包，起名 cache → myorg/cache，结果发现 Laravel 的 illuminate/cache 存在，这没关系；但万一别人早注册了 myorg/cache，你就彻底没戏。
性能 / 兼容性影响：名字太泛会导致用户混淆，比如 myorg/router 和 nikic/fast-route 功能重叠，但 Composer 完全不管语义，只按字面匹配。下游用户 require 错了，debug 成本远高于命名时多打三个字母。
- 加领域限定词：不用
logger，用aws-logger或audit-logger - 加技术栈标识：不用
validator，用laravel-validator或psr-validator - 别依赖版本号进 package 名（如
mylib-v2）——Composer 的版本约束机制就是干这个的，名字里塞版本是反模式
私有包绕过 Packagist 占用问题，但必须改 composer.json 配置
如果你的包只供内部使用，根本不想上 Packagist，那就别跟它较劲。但默认情况下，Composer 仍会向 Packagist 查询所有包，包括你声明的私有 vendor/package，查不到就报错。
关键点在于：必须关闭 Packagist 默认源，并显式声明你的私有源位置。不是加个 repositories 就够，还要关掉默认行为。
- 在
composer.json顶层加："packagist.org": false（放在repositories数组里） - 再加一条
vcs类型仓库，指向你的 Git 地址：{"type": "vcs", "url": "https://git.example.com/myorg/mylib"} - 确保 Git 仓库根目录有合法
composer.json，且name字段严格匹配你 require 的vendor/package - 别忘了给 CI/部署机配好 SSH key 或 token，否则
composer install会卡在 clone 阶段
最常被忽略的是 packagist.org: false 这一行——少了它，Composer 依然先查 Packagist，报错优先级高于你的私有源。
