如何通过Composer.json配置自动从Git仓库安装私有插件？

需在composer.json中配置repositories为vcs类型并指定git仓库URL，require中声明与私有包composer.json内一致的name及对应tag或dev分支版本，https需用Token认证，ssh需配置密钥，无stable tag时可用“dev-branch as version”绕过稳定性限制。

配置 repositories 指向私有 Git 仓库

Composer 默认只从 packagist.org 拉包，要装私有插件，必须显式告诉它“去哪找”。关键是在 composer.json 顶层加 repositories 字段，类型设为 vcs，并填入仓库 URL。

注意：URL 必须是可被 Composer 克隆的地址（支持 HTTPS 或 SSH），且仓库根目录下要有合法的 composer.json 文件（含 name 和 version 字段）。

• HTTPS 方式需确保凭据可用（如已配置 git credential 或使用 token 替代密码）
• SSH 方式要求本地有对应私钥且 ssh-agent 已加载
• 不能用 github/gitlab 的网页地址（如 https://github.com/user/repo），得用 Git 协议地址（如 https://github.com/user/repo.git 或 git@github.com:user/repo.git）

{   "repositories": [     {       "type": "vcs",       "url": "https://github.com/your-org/your-private-plugin.git"     }   ] }

在 require 中声明插件包名和版本

私有包的 name（如 your-org/your-private-plugin）必须与它自己 composer.json 中的 name 完全一致；版本号则取决于你如何打 tag 或写分支别名。

Composer 会自动识别 Git 仓库里的 git tags（格式如 v1.0.0、1.0.0），也支持 dev- 前缀的分支名（如 dev-main）。但注意：dev-main 不是稳定版，安装时需显式指定，否则可能因稳定性策略被跳过。

• 要装带 tag 的正式版：用 "your-org/your-private-plugin": "^1.0"
• 要装 main 分支最新：用 "your-org/your-private-plugin": "dev-main"
• 若私有包未打 tag，又没启用 minimum-stability，composer install 会报错“could not find package”

{   "require": {     "your-org/your-private-plugin": "^1.0"   } }

处理认证失败和访问权限问题

私有仓库拉取失败最常见的原因是认证被拒，错误信息通常是：Failed to clone https://github.com/xxx/xxx.git via https, ssh protocols，或更具体的 403 Forbidden / Permission denied (publickey)。

解决路径取决于协议：

• HTTPS：改用个人访问令牌（PAT）代替密码，URL 写成 https://@github.com/xxx/xxx.git；或配置 git credential helper 缓存凭据
• SSH：确认 ssh -T git@github.com 能通，且 ~/.ssh/config 中 host 别名与仓库 URL 中的 host 一致（如 github.com vs git@github.com）
• GitLab 自托管？确保 composer.json 中的 URL 匹配其项目实际克隆地址（含端口、子路径等）

避免 minimum-stability 引发的意外降级

私有包若只有 dev- 分支而无 stable tag，Composer 默认不会装——因为全局 minimum-stability 是 stable。强行加 "minimum-stability": "dev" 会影响所有依赖，带来不可控的 dev 版本混入。

更稳妥的做法是局部放宽：在 require 条目后加 @dev 后缀，仅对这个包生效。

• 错误写法："your-org/your-private-plugin": "dev-main"（仍受 stability 策略限制）
• 正确写法："your-org/your-private-plugin": "dev-main as 1.0.0" 或 "your-org/your-private-plugin": "dev-main@dev"
• 推荐用 as 别名方式，既绕过稳定性检查，又让版本约束逻辑清晰

{   "require": {     "your-org/your-private-plugin": "dev-main as 1.0.0"   } }

真正卡住人的往往不是配置语法，而是 Git 仓库本身没暴露正确的包信息，或者认证链某处断了。动手前先手动 git clone 那个 URL 看能不能通，再检查私有包的 composer.json 是否有 name、是否在根目录——这两点漏掉一个，Composer 就完全找不到包。