必须显式在composer.json的repositories字段中声明type为"vcs"且url为可clone地址，否则require写对包名也会报错；包名须与仓库composer.json的name字段完全一致，版本需用dev-main等合法分支标识。
Composer 自定义仓库不能靠猜，必须显式声明类型和地址，否则 require 里写对包名也没用。
repositories 字段必须显式声明 vcs 类型
Composer 不会自动把 Git 地址当包源，repositories 是唯一入口。不加这个字段，哪怕 require 里写了正确的包名，也会报 [InvalidArgumentException] Package vendor/name not found。
常见错误写法："url": "git@github.com:org/repo.git" 单独丢进 require —— 这根本不是 Composer 认可的依赖格式。
- 必须用
vcs类型，且url指向可git clone的地址（HTTPS 或 SSH） - SSH 地址需本地已配置密钥，且
ssh-add -l能列出对应私钥 - HTTPS 地址若私有，后续要配 token 或
auth.json，不能裸写密码 - 多个仓库就写多个对象，顺序无关，Composer 会逐个扫描
包名和版本号必须与目标仓库 composer.json 严格一致
Composer 安装时会读取远程仓库根目录下的 composer.json，提取 name 和可用版本。如果两边不匹配，就会跳过该仓库、继续找 Packagist，最终失败。
典型不一致场景：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 目标仓库
composer.json里写的是"name": "acme/utils"，但项目中require写成"acme/toolkit" - 用了
master或main当版本号 —— 正确写法是dev-main（分支名前加dev-）或带 hash 的dev-main#abc123 - 目标仓库没打 Git tag，又没设
"minimum-stability": "dev"，^1.0这类约束会直接忽略dev-分支
认证信息别塞进 composer.json，走 auth.json 或全局 config
把 token、密码、SSH 密钥路径硬编码进 composer.json 是高危操作，尤其当项目要提交到 Git 时。Composer 提供了更安全的加载路径。
推荐做法：
- HTTPS + Token：用
composer config --global github-oauth.github.com <token>，凭证存在~/.composer/auth.json，自动携带 - SSH：确保执行
composer install的用户能读~/.ssh/id_rsa，且ssh-agent已加载密钥（ssh-add -l可验证） - 自建 HTTPS 仓库带自签名证书：必须全局设置
ssl.cafile，路径指向完整 PEM 链（中间 CA + 根 CA），且 PHP 进程有读权限 - CI/CD 环境：优先用环境变量注入 token，再通过
composer config命令动态写入，避免敏感信息落盘
私有包没生效？先手动验证克隆和 composer.json 可读性
Composer 报错常掩盖真实原因。与其反复改配置，不如分步确认基础链路是否通。
排查顺序：
- 在项目目录下，用同一用户执行
git clone https://github.com/org/repo.git /tmp/test-clone—— 若失败，说明网络、认证或地址本身就有问题 - 进克隆目录，检查
composer.json是否存在、JSON 格式合法（php -l composer.json）、name字段值与require中完全一致（包括大小写和斜杠方向） - 运行
composer install -vvv，看日志里是否出现Cloning into '/path/to/cache/...，以及有没有Reading composer.json of vendor/name (dev-main) - 如果用 Satis 或私有 Composer 服务，确认
repositories类型是composer而非vcs，且 URL 指向的是packages.json所在的根路径（如https://packages.example.com，不是https://packages.example.com/satis.json）
最常被忽略的一点：私有仓库的 composer.json 必须包含 autoload 配置，否则即使安装成功，自动加载也会失效 —— 这不是仓库配置问题，而是包自身合规性问题。
