Composer配置镜像不生效的根本原因是键名写错（应为repo.packagist单数）、缺失type值（必须显式写composer）、URL末尾缺/；三者任一出错均导致静默失效，查config为空但无报错。
镜像地址配错，Composer 就会静默走官方源——不报错、不提示、只慢、只失败。
composer config -g repo.packagist 命令为什么总不生效
根本原因就三个：键名写错、type 缺失、URL 末尾少 /。Composer 2.x 严格认 repo.packagist（单数 repo，不是 repos），漏掉 composer 这个 type 参数，或 URL 写成 https://mirrors.aliyun.com/composer（缺斜杠），都会导致配置存进无效字段，composer config -g repo.packagist 查出来是空或 null，但命令本身不报错。
验证是否真生效，别只看 config 输出，运行 composer diagnose，检查 Repo packagist.org: 后面是不是你设的镜像地址；或者执行 composer install -vvv，看日志里请求的是不是 packages.json 的镜像路径。
- Windows 用户执行完要关掉当前终端重开，否则 shell 可能仍读取旧缓存
- CI 环境中用
sudo composer config -g，结果写进了root用户的~/.composer/config.json，但构建用的是普通用户，根本读不到 - 项目根目录下只要存在
composer.json并含"repositories"字段（哪怕空数组），全局配置就完全失效
repositories 数组顺序为什么决定包能不能装上
Composer 按 repositories 数组从上到下的顺序查包，一旦名字匹配，立刻停止搜索。这意味着私有包仓库必须放在 Packagist 官方源之前，否则 acme/utils 这种包名在 packagist.org 找不到，Composer 直接报 Could not find package，根本不会往后看你的私有源。
常见错误配置：
- 把
{"type": "composer", "url": "https://packagist.org"}放在数组最前面，私有源再往后 —— 私有包永远不被扫描 - 两个
vcs类型仓库都声明了acme/utils，只有第一个生效，第二个被忽略 - 项目级
composer.json里写了"packagist.org": false，但没同步配好自己的repositories，结果所有包都找不到
type: vcs 和 type: composer 的区别不能混用
填错 type 是静默失败的高发区。Composer 靠 type 决定怎么解析 url，不是所有 URL 都能当源用。
-
type: vcs→ 对应 Git/SVN/Hg 地址，Composer 会git clone并读取其中的composer.json；适合单个私有库，但要求目标分支根目录有合法composer.json，且name是vendor/name格式 -
type: composer→ 对应提供packages.json的 HTTP 服务（如阿里云镜像、Satis 页面）；URL 必须可访问packages.json，且末尾带/，否则拼出/packages.json路径 404 - 把 Satis 服务地址当成
vcs配，Composer 就去按 Git 协议连，而不是走 HTTP API，结果卡死或报模糊错误
离线环境用 artifact 仓库时命名和结构必须严格对齐
artifact 是 Composer 原生支持的离线模式，但它不宽容：压缩包名、内部结构、配置路径三者必须完全一致，否则 composer install 会跳过该包，甚至不提示。
- 压缩包必须命名为
vendor-name/package-name-version.tar.gz，例如acme/utils-1.2.0.tar.gz - 每个压缩包内必须包含完整
composer.json，且其中name和version字段要与文件名完全一致 - 配置命令为
composer config repositories.offline '{"type":"artifact","url":"/path/to/artifacts/"}'，url必须是本地绝对路径或可被 Web 服务器直接GET的路径 - 若用相对路径（如
../artifacts），换机器或 CI 环境就失效；若压缩包里少了autoload字段，自动加载会崩
最易被忽略的一点：所有自定义仓库配置，无论是全局、项目级还是环境变量，最终都服务于 composer.lock 的生成逻辑。一旦 lock 文件里记录的 dist.url 还是 https://api.github.com 这类远程地址，离线或切换源后 install 仍会失败——必须确保 lock 文件是在目标源环境下生成的。
