如何入门设置Composer默认为Packagist源？

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

使用Composer时，默认仅接受来自 packagist.org 的包。这个默认并非固定在代码中不可更改，而是一种可覆盖的配置逻辑：

怎么查当前生效的 Packagist 源

别猜，直接看配置：

• 全局配置（影响所有项目）：composer config -g repo.packagist —— 返回 JSON 表示已设镜像，空输出或报错表示走默认 https://packagist.org
• 项目级配置（仅当前目录）：composer config repo.packagist（不带 -g）—— 如果返回值存在，它会**完全屏蔽**全局配置
• 想确认最终行为？加 -vvv 跑一次命令，比如 composer require monolog/monolog --no-install -vvv，终端里会打印出实际请求的 URL，这才是真相

全局换源必须写对三个字段

这条命令最常敲错：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

缺一不可：

• repo.packagist：key 名必须是这个，不能是 repos.packagist（多一个 s 就失效）、也不能是 packagist（少前缀）
• composer：这是 type 值，不是可选参数，漏掉会导致 Composer 降级回默认源
• https://mirrors.aliyun.com/composer/：必须用 HTTPS，末尾**不能加斜杠**（注意：和私有 repositories 配置相反，这里加斜杠在某些 Composer 版本会报 Invalid repository type）

项目级配置为什么更可靠

团队协作或 CI 环境里，全局配置容易引发不一致问题。项目级写法直接进 composer.json，所有人行为统一：

• 先关掉默认源：{"packagist.org": false} 必须写在 repositories 数组里，且建议放**最后**（避免误删）
• 再加镜像源：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，放在数组开头
• 顺序决定优先级：Composer 从上到下匹配包，同名包一旦在第一个源命中，后面全跳过
• 别手动编辑 composer.json 的 repositories —— 用命令追加：composer config repositories.0.type composer 等，避免格式错误

为什么禁用 packagist.org 很容易漏掉

很多人以为“我只写了私有源，那肯定走私有”，结果还是装到了官方版同名包。根本原因是：packagist.org 是 Composer 的隐式源，不显式关掉，它永远在后台参与解析。

关键点：

• "packagist.org": false 必须作为 repositories 数组中的一项，不是顶层字段
• 它不能和私有源写成同一对象，必须拆开，例如：[{"type":"composer","url":"https://my-private.com/"},{"packagist.org":false}]
• 如果关了又想保留公共包能力，得手动补回官方源：{"type":"composer","url":"https://packagist.org/"}，否则连 monolog/monolog 都装不了

最容易被忽略的是：禁用操作不是“开关”，而是“移除参与权”。一旦漏掉，Composer 就会在私有源没命中的时候，默默 fallback 到官方源拉包——你根本看不到日志里那行请求，除非加 -vvv。