必须在项目根目录composer.json中显式声明repositories数组,且每项type必须为"vcs"、url须为可git clone的Git地址(含.git后缀),认证需通过权限600的~/.composer/auth.json配置http-basic字段。

在 composer.json 中配置私有仓库的 repositories 字段
Composer 默认只从 packagist.org 拉包,要拉私有 Git 仓库(如 GitHub 私库、GitLab 内网库、Bitbucket),必须显式声明源。关键不是改全局设置,而是改项目级 composer.json 的 repositories 数组。
常见错误是把仓库地址写成 HTTPS 克隆地址(如 https://github.com/yourorg/private-package.git),但 Composer 要求的是「仓库元数据源」——即能返回 composer.json 的位置。Git 类型仓库直接填 Git URL 即可,Composer 会自动解析其根目录下的 composer.json。
- 支持类型包括
"type": "vcs"(Git / SVN / Mercurial)、"type": "package"(手动定义单个包)、"type": "composer"(指向另一个支持 Composer 插件协议的源) - 顺序很重要:
repositories是从上到下查找的,私有包应放在 packagist 前面,否则可能被跳过 - 如果私有库用 SSH,确保本地已配好 SSH key 且
git@...地址能正常 clone;用 HTTPS 则需提前配置凭据或启用git config --global credential.helper store
composer require 时指定版本并强制走私有源
即使配置了 repositories,执行 composer require vendor/package 仍可能报 Could not find package vendor/package —— 这通常是因为该包名未在任何已知源中注册(packagist 上没有,私有源又没被触发)。根本原因是 Composer 默认只查 packagist,除非你明确告诉它“这个包就来自我刚配的私有源”。
解决方法是:在 require 后加 --repository-url 或直接在 composer.json 的 require 中写死版本约束,并确保包名与私有库 composer.json 中的 "name" 完全一致(包括大小写)。
- 推荐做法:先在
composer.json手动加"vendor/package": "dev-main"(或具体 tag),再运行composer update vendor/package - 避免用
dev-master:很多私有库已弃用master分支,改用main,写错分支名会导致安装失败 - 如果私有库未打 tag,Composer 默认只认
dev-开头的开发分支别名,不能写"*"或省略版本
私有 GitLab/GitHub 仓库需要 token 认证怎么办
当私有仓库托管在 GitHub 或 GitLab 且启用了 token 访问控制时,单纯配 repositories 不够,Git 操作会卡在认证环节。Composer 本身不处理 HTTP Basic Auth,但可通过 Git 凭据系统透传。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
最稳定的做法不是把 token 塞进 URL(不安全且易泄露),而是让 Git 自动注入认证头:
- GitHub:运行
git config --global url."https://<code>your-token@github.com/".insteadOf "https://github.com/" - GitLab:类似,用
https://<code>your-token:x-oauth-basic@gitlab.example.com 替换原域名 - 验证是否生效:执行
git ls-remote https://github.com/yourorg/private-package.git,能列出 ref 就说明通了 - 注意:Composer 的
create-project或install过程中若涉及子模块或递归 clone,也依赖同一套 Git 配置
为什么 composer install 有时仍走公网源,不拉私有包
典型现象是:composer.lock 里记录的 dist URL 是 packagist 的 CDN 地址,而不是你的私有 Git 地址。这是因为 lock 文件生成时,Composer 已缓存了包信息,后续 install 直接按 lock 里的 URL 下载,不再查 repositories。
这意味着:如果你后来才加私有源,或者私有库更新了但没重新 update,install 就不会感知变更。
- 每次修改
repositories或私有库的composer.json后,必须运行composer update vendor/package --with-dependencies来刷新 lock - CI 环境中要确保
composer install前,Git 凭据和repositories配置已就位,否则会因无法访问而失败 - 私有包若有
replace或provide字段,可能干扰依赖解析,建议初期先去掉这些字段做最小验证
私有包的调试核心就两条:一是确认 composer.json 的 name 和 version 能被准确匹配,二是确保 Git 层的网络和认证在 Composer 执行时真实可用——这两处任一出问题,都会静默降级到失败。

















