如何通过Composer设置自定义仓库地址？

本文共计1012个文字，预计阅读时间需要5分钟。

Composer 指定仓库不是加个URL就行为，核心在于type判断、顺序控制和packagist.org的格式禁用——漏掉任意一项，就可能从非官方源偷偷安装，版本对不上还查不出原因。

怎么写 repositories 才算生效

repositories 是个数组，每项必须带 type 和对应字段（如 url），缺一不可。没写 type，Composer 直接忽略整条配置；写错 type（比如把私有 Packagist 服务配成 vcs），就会去走 Git clone 流程，结果 404 或静默失败。

• type: composer → 对应提供 packages.json 的 HTTP 服务，url 必须以 / 结尾（如 "https://packages.example.com/"），否则拼出的请求路径错误
• type: vcs → 对应 Git/SVN/Hg 仓库地址，支持 https://、git@、ssh://，但别混用认证方式（HTTPS 加 token + SSH 私钥 = 冲突）
• type: package → 手动声明单个包的 dist、autoload 等，维护成本高，仅适合闭源二进制包
• 所有自定义源必须放在 repositories 数组**首位**，否则 Packagist 会先命中同名包

为什么 require 的包没走你配的源

常见现象是 composer require acme/utils 装出来的却是 Packagist 上的老版本，甚至报 Could not find package。根本原因不是配置没读到，而是 Composer 的匹配逻辑被绕过了。

• 包名（vendor/name）必须和你仓库中 composer.json 的 name 字段完全一致
• 即使你写了自定义源，只要没显式关闭 packagist.org，Composer 仍会去官方源查一遍——它不“覆盖”，只“并行”
• 执行 composer show acme/utils 看是否列出；不行就跑 composer install -vvv，搜日志里有没有 Reading repository 后跟你的 URL
• 确认你的 VCS 仓库根目录下有合法 composer.json，且含 name 和 version（或打了 Git tag）

全局 vs 项目级配置谁优先

项目根目录下的 composer.json 里的 repositories 永远优先于全局 ~/.composer/config.json。很多人改了全局镜像，却在项目里又加了一套私有源，结果发现还是走官方源——其实是项目配置里漏了 "packagist.org": false，全局镜像又被项目默认源覆盖了。

• 查全局源：运行 composer config -g repos.packagist
• 查项目源：进项目目录后运行 composer config repos.packagist（去掉 -g）
• 禁用默认源必须显式写：{"packagist.org": false} 放在 repositories 数组里，不能只靠删掉默认项
• 改完务必执行 composer clear-cache，否则旧元数据还在缓存里，install 还是拉错

换源后 vendor/autoload.php 找不到类

这不是 autoload 配置问题，而是路径硬编码导致的——vendor/autoload.php 是生成时写死的入口文件。你改了 config.vendor-dir 或换了源，但没重建整个 vendor 目录，PHP 还在找原来的路径。

• 改了 vendor-dir 后，必须删掉现有 vendor 目录，再跑 composer install（dump-autoload 不够）
• 代码里所有 require 'vendor/autoload.php' 都得同步改成新路径，比如 require 'third-party/autoload.php'
• IDE（如 PHPStorm）默认只索引 vendor，需手动在 Settings → PHP → Include Paths 中添加新路径
• 如果用了 composer/installers 配 installer-paths，注意它只对声明了 type（如 wordpress-plugin）的包生效，普通库不受影响