必须由实际运行composer的用户（如www-data）执行且带-g参数，否则配置写入/root/.composer无效；命令三要素缺一不可：键名repo.packagist（单数）、type值显式为composer、url须https且末尾带斜杠。
composer config -g repo.packagist 命令必须带 -g 且由目标用户执行
后台静默执行的前提是：命令必须由实际运行 Composer 的用户（比如 www-data、nginx 或部署用的普通用户）执行，不能用 sudo 随意切到 root。否则配置写进 /root/.composer/config.json，而 PHP 进程根本读不到。
常见错误是写成：sudo composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/——这只会配到 root 用户，对 Web 服务无效。
- 先确认目标用户：
whoami或查 Web 服务配置（如 Nginx 的user指令、Supervisor 的user=字段） - 用该用户身份执行：
sudo -u www-data composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 若目标用户无 shell（如
www-data默认 shell 是/usr/sbin/nologin），需临时指定 shell：sudo -u www-data -s /bin/bash -c "composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/"
命令三要素缺一不可，否则静默失效
哪怕在后台执行，composer config -g repo.packagist 仍必须严格满足三个硬性条件，错一个就白跑——不报错、不提示、也不生效。
- 键名必须是
repo.packagist（单数repo，不是repos.packagist） - 第二个参数必须显式写
composer（这是 type 值，漏掉则 fallback 到官方源） - URL 必须是 HTTPS 且末尾带
/，例如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌
验证是否真写进去了：sudo -u www-data composer config -g repo.packagist，输出应为完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null 或还是 https://repo.packagist.org，说明没生效。
项目级配置会完全覆盖全局镜像
后台脚本即使配对了全局源，只要项目根目录下 composer.json 含 "repositories" 字段，Composer 就直接忽略全局配置，走项目定义的源——这是优先级规则，不是 bug。
- 检查是否存在干扰：
grep -A3 '"repositories"' /path/to/project/composer.json - 常见陷阱包括：
"repositories": []、"repositories": {"packagist.org": false}、或硬编码了https://repo.packagist.org - 临时绕过项目配置测试：在项目目录下运行
composer config --unset repositories（注意不加-g）
清缓存是后台执行后必须补的一步
配置写对了，但不清理缓存，Composer 仍会从旧缓存里读元数据——结果就是 composer update 找不到新版本、依赖解析失败，看起来像“配置没起作用”。
- 后台执行后务必加一句：
sudo -u www-data composer clear-cache - 验证缓存路径：
sudo -u www-data composer config --list | grep cache，确保指向~/.composer/cache（非 root 路径） - 若缓存目录被锁住（如 IDE 正在扫描），
clear-cache可能不彻底；可手动清：sudo -u www-data rm -rf ~/.composer/cache/*
真正容易被忽略的不是命令怎么写，而是用户上下文、项目级覆盖、缓存残留这三点——它们不会报错，但会让整个配置流程看起来“莫名其妙地失效”。
