Composer包名必须为全局唯一的vendor/name格式,如monolog/monolog;命名空间不参与包发现与安装,仅用于自动加载映射,二者完全解耦。

包名必须全局唯一,不能只靠命名空间区分
Composer 包名(如 monolog/monolog)是 Packagist 上的唯一标识,由 vendor/name 构成。哪怕你本地用 MyCompanyUtils 命名空间,只要没注册 mycompany/utils 这个包名,别人就无法通过 composer require mycompany/utils 安装它——命名空间不参与包发现和安装流程。
常见错误是误以为“只要命名空间不冲突,包名随便起”,结果在团队协作或发布时:
- composer require utils 报错找不到包
- 同名但不同 vendor 的包被他人抢先注册(如 acme/utils 被占用)
- CI 构建失败,因为私有包未配置自定义仓库
命名空间应与 vendor 和包名对齐,否则 autoload 会失效
PSR-4 自动加载依赖路径映射,而映射逻辑默认期望命名空间前缀与包名 vendor 一致。比如你发布包 myorg/http-client,composer.json 中写:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
{
"autoload": {
"psr-4": {"MyOrg\HttpClient\": "src/"}
}
}这是合理且可预期的;但如果写成 {"App\": "src/"} 或 {"VendorX\": "src/"},下游用户引入后,类 MyOrgHttpClientClient 就无法被自动加载——因为 Composer 生成的 autoloader 只认你声明的前缀。
所以实际操作中要确保:
- vendor/name(包名)反映组织/项目归属
- 命名空间根(如 MyOrgHttpClient)与 vendor 名部分一致(大小写可灵活,但语义应对应)
- autoload.psr-4 键值对中的键必须精确匹配你代码里 namespace 声明的开头部分
- 不要为了“通用性”把命名空间设成 Shared 或 Common 这类无归属前缀
私有包也要遵守命名规范,否则无法被正确 require
如果你在内部 Git 仓库托管私有包(如 git@corp.com:php/my-utils.git),仍需在它的 composer.json 中设置合法的 name 字段,例如 "corp/my-utils"。否则:
- 其他项目执行 composer require corp/my-utils 会失败(Composer 找不到匹配的包)
- 即使加了自定义 repository,Composer 仍以 name 字段为索引去匹配,不是靠 URL
- 私有包若省略 name 或填空值,composer install 会报 Package name is invalid
同时注意:
- name 中的 vendor 段建议小写、无下划线、不含特殊字符(Packagist 强制校验)
- 若使用 Satis 或 Private Packagist,name 必须与其仓库元数据一致,否则同步失败
- 不要用 dev- 前缀伪造版本,那属于 version 字段的职责,跟包名无关
多包共用同一命名空间时,autoload 映射必须明确隔离
当多个 Composer 包共同提供 MyOrgCore 下的类(比如 myorg/core、myorg/validation、myorg/logging),每个包的 autoload.psr-4 必须只映射自己负责的子命名空间:
// myorg/core/composer.json
"autoload": {"psr-4": {"MyOrg\Core\": "src/"}}
<p>// myorg/validation/composer.json<br />
"autoload": {"psr-4": {"MyOrgValidation": "src/"}}</p><p>// myorg/logging/composer.json
"autoload": {"psr-4": {"MyOrgLogging": "src/"}}如果某个包错误地写了 {"MyOrg\": "src/"},就会覆盖其他包的映射,导致类加载冲突或漏加载。更隐蔽的问题是:
- composer dump-autoload --optimize 会合并所有 PSR-4 映射,但不会检测重叠
- IDE 可能因映射范围过大而索引混乱,跳转到错误文件
- 单元测试中 mock 类可能被错误的 autoloader 加载,掩盖真实依赖关系

















