需在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 必须是可被 Comp

• 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 就完全找不到包。