如何通过配置文件修改全局Composer镜像源配置-composer-PHP中文网

手动编辑 config.json 比命令更可控，必须确保 repositories 数组首项为 {"packagist.org": false}、次项为镜像源且 url 末尾带斜杠，并清缓存验证生效。

如何通过配置文件修改全局composer镜像源配置

直接编辑 `config.json` 文件比命令更可控

用 composer config -g 命令改镜像，看似方便，但漏掉 composer type 参数、写错键名（比如 repos.packagist）、URL 少斜杠，都会静默失效——命令不报错，composer install 却照连 packagist.org。手动改文件能一眼确认三要素是否到位：字段路径、禁用默认源、URL 结尾斜杠。

~/.composer/config.json（Linux/macOS）或 %APPDATA%\Composer\config.json（Windows）是用户级配置真实落盘位置
必须确保顶层有 "repositories" 数组（不是 "repo.packagist" 对象），且第一项为 {"packagist.org": false}
第二项才是镜像源：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，url 末尾的 / 不可省
别用记事本或带格式编辑器保存；推荐 VS Code 或 Notepad++，编码选 UTF-8 无 BOM
改完可用 jq . ~/.composer/config.json（Linux/macOS）快速校验 JSON 合法性

`repositories` 数组结构不能颠倒也不能缺项

Composer 要求 "packagist.org": false 必须放在 "repositories" 数组首位。如果只写镜像对象、或把禁用语句放后面，它仍会向官方源发起元数据请求，导致卡在 Loading composer repositories 或 fallback 到 packagist.org。

错误写法（只有一项、没禁用、顺序错）："repositories": [{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}]

正确最小结构（两项、顺序固定、url 带斜杠）：

{ "repositories": [ {"packagist.org": false}, {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} ] }

空数组、"repositories": [] 或缺失该字段，等同于未配置，Composer 自动启用默认源

改完必须清缓存，否则日志里还是看到 `packagist.org`

Composer 缓存的是 packages.json 元数据，不是包本身。即使配置已写对、文件路径也正确，只要缓存里还存着旧的官方源索引，composer update 就仍会去请求 https://packagist.org/packages.json ——你看到的“慢”，其实是缓存在作祟。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

执行 composer clear-cache 是最稳妥方式（清全部）
也可手动删缓存目录：rm -rf ~/.composer/cache/repo/https---packagist.org/ 和对应镜像路径
验证是否真走镜像：运行 composer update -vvv 2>&1 | grep "Downloading"，看输出中域名是不是你配的镜像地址
别只信 composer config -g repo.packagist 输出；它可能显示 URL，但实际没落地，或被缓存掩盖

多用户环境（CI/宝塔/Docker）下，`~/.composer/config.json` 往往不生效

你在终端里用普通用户执行成功，不代表 Web 服务、定时任务或 CI 流水线能读到同一份配置。它们常以 www-data、runner 或容器内非 root 用户运行，根本读不到你的家目录下的 config.json。

真正全局生效的唯一路径是 /etc/composer/config.json（Composer 2.2+ 支持）
该文件需属主 root:root、权限 0644，内容结构与用户级一致，但 "repositories" 是顶层字段
CI 中若用 Docker，必须 COPY /etc/composer/config.json 进镜像，不能靠构建时 composer config -g
宝塔面板执行命令前，先确认用户：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/