必须在composer.json顶层repositories字段中声明type为"vcs"的私有仓库url（含.git后缀），并确保require中包名与私有库composer.json的name完全一致、版本约束正确（如dev-main），同时配置ssh密钥或https+pat认证，否则报“could not find a matching version”。
要在项目中直接安装 GitHub、GitLab 等 Git 仓库里的代码作为 Composer 依赖，必须让 Composer 明确知道该仓库的存在、可访问性及包名匹配规则——缺一不可，否则会报 Could not find a matching version of package。
在 composer.json 中声明私有仓库源
打开项目根目录下的 composer.json 文件，在顶层添加 repositories 字段（不是嵌套在 config 或 scripts 下）：
确保数组格式合法：每项必须是对象，【type 必须为 "vcs"】，不能写成 "git" 或留空；URL 必须是完整可 git clone 的地址，含 .git 后缀。
例如 GitHub 仓库：
{ "repositories": [ { "type": "vcs", "url": "https://github.com/yourname/private-package.git" } ], "require": { "yourname/private-package": "dev-main" }}
注意：repositories 必须位于最外层，与 require、autoload 并列；多条仓库配置时，逗号不能遗漏，尤其数组末尾新增项后——JSON 语法错误会导致整个 composer install 失败。
认证方式选择与配置
方法一：SSH 密钥（推荐，适合 CI/CD 和本地开发）
生成密钥：ssh-keygen -t rsa -b 4096 -C "you@example.com"；将公钥内容（~/.ssh/id_rsa.pub）添加到 GitHub/GitLab 账户的 SSH Keys 设置中；测试连接：ssh -T git@github.com。
然后把 repositories.url 改为 SSH 格式："url": "git@github.com:yourname/private-package.git"。
方法二：HTTPS + 个人访问令牌（PAT）
GitHub 上生成 Token，权限至少勾选 repo；修改 URL 为："url": "https://oauth2:glpat-xxx@gitlab.com/yourname/private-package.git"（注意替换为真实 Token）；或通过全局配置避免硬编码：composer config --global http-basic.gitlab.com oauth2 glpat-xxx。
【auth.json 必须放在用户级路径】：Linux/macOS 是 ~/.composer/auth.json，Windows 是 %APPDATA%\Composer\auth.json，且权限必须设为 600（chmod 600 ~/.composer/auth.json），否则 Composer 静默忽略。
正确指定包名与版本约束
第一步：确认私有仓库根目录的 composer.json 中 "name" 字段值，例如 "acme/utils"。
第二步：主项目 require 中必须完全一致地写入该 name，【不能大小写混用、不能加下划线、不能省略 vendor 段】。
第三步：版本约束按需填写：
→ 引用分支：用 dev- 前缀，如 "acme/utils": "dev-main"（对应远程分支 main）；
→ 引用 Tag：写带 v 的语义化版本，如 "acme/utils": "v1.2.0"；
→ 引用某次提交：用 dev-main#abc1234 格式，# 后必须是完整 SHA1，不是分支名。
注意：未打任何 Tag 时，唯一可用版本就是 dev-main（或 dev-master，取决于默认分支名）；"main" 或 "*" 会被当成模糊约束，去 Packagist 查找，必然失败。
强制拉取最新代码（跳过 vendor 缓存）
Composer 默认复用 vendor/ 下已有的 Git 克隆，只更新 composer.lock 记录的 commit，不会自动 git pull。
若你已推送新提交到远程分支，但 composer update 仍没生效，执行：
rm -rf vendor/acme/utils → composer install。
这一步会清空旧克隆，重新从 Git 源拉取当前约束匹配的最新 commit。
