如何用Composer管理PHP私有依赖包-composer-PHP中文网

composer install 能装上私有包，前提是它被 composer “看见”且“认得”：repositories 必须位于项目级 composer.json 顶层，type 为 "vcs" 或 "composer"，url 为可克隆地址，auth.json 路径权限结构正确，require 中包名与私有包 composer.json 的 name 逐字符一致，且私有包自身需正确定义 autoload 规则。

如何用composer管理php私有依赖包

composer install 能装上私有包，但前提是它被 Composer “看见”且“认得”——不是加了 URL 就行，而是整个链路（仓库声明、认证、包名、自动加载）必须严丝合缝。

repositories 必须写在项目级 composer.json 顶层

Composer 只在项目根目录的 composer.json 文件顶层读取 repositories 字段。塞进 config、extra 或子对象里，等于没写。

✅ 正确位置："repositories": [{ "type": "vcs", "url": "https://gitlab.example.com/myorg/utils.git" }]
❌ 错误写法："config": { "repositories": [...] } 或 "extra": { "repositories": [...] }
⚠️ type 值只能是 "vcs"（对应 Git/SVN/Hg 仓库）或 "composer"（对应 Satis/Packagist Enterprise 等私有 Composer 仓库），不能填 "git" 或留空
⚠️ url 必须是可 git clone 的地址，比如 https://gitlab.example.com/group/repo.git，而不是网页地址 https://gitlab.example.com/group/repo

auth.json 的路径、权限和结构三者缺一不可

Composer 不走系统 Git 凭据，也不读 SSH agent，只认 auth.json，而且只在特定条件下生效。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

✅ 文件位置：必须放在项目根目录（优先）或全局 ~/.composer/auth.json；项目级会覆盖全局
✅ 权限必须是 600：chmod 600 auth.json，否则 Composer 直接跳过
✅ 结构要严格匹配域名：若仓库 URL 是 https://gitlab.example.com/myorg/utils.git，则 auth.json 中的 key 必须是 "gitlab.example.com"，不能带端口、路径、协议前缀
✅ Token 类型要对得上：GitLab 用 glpat- 开头的 Personal Access Token，填在 http-basic 的 password 字段；OAuth2 场景才用 username: oauth2

require 中的包名必须与私有包 composer.json 的 name 完全一致

大小写、分隔符、vendor 名全部逐字符敏感。Composer 解析依赖时靠这个字符串去匹配仓库中所有已知包，错一个字符就“找不到”。

❌ 私有包 composer.json 里写的是 "name": "MyOrg/utils"，你在主项目 require 里写 "myorg/utils" → 报 Could not find package
❌ 写成 "MyOrg/Utils" 或 "myorg-utils" 同样失败
✅ 验证方式：进入私有包仓库，直接看它的 composer.json 文件第一行 "name" 字段值，原样复制粘贴到主项目的 require

autoload 不生效？不是没下载，是没生成映射

即使 composer install 显示 Installing myorg/utils (dev-main)，new UtilsClass() 仍报 Class not found，大概率是 autoload 没触发或配置错误。

✅ 私有包自己的 composer.json 必须定义 autoload 段，例如："autoload": { "psr-4": { "MyOrg\Utils\": "src/" } }
✅ 主项目执行 composer dump-autoload 才会重新扫描并合并所有依赖的 autoload 规则
✅ 若私有包用的是 classmap 或 files，确保路径存在且可读；PSR-4 映射的命名空间前缀必须与实际文件路径结构一致
⚠️ 注意：私有包的 autoload 是它自己的责任，主项目不负责替它补规则