脚本执行 composer config 必须显式切换目标用户、验证 PHP 环境（HTTPS/openssl/phar.readonly）、兼顾项目级 repositories 覆盖逻辑，并强制清理缓存，否则镜像配置无效。
脚本里直接执行 composer config 会写错用户配置
很多运维同学写完同步脚本，跑完 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，发现目标服务器上 composer install 还是连 packagist.org——根本原因是命令默认写进了当前 shell 用户（比如 root）的 ~/.composer/config.json，而 WebStation、宝塔网站进程、systemd 服务实际用的是 admin 或 www 用户。脚本必须显式切换用户再执行。
- 用
sudo -u admin /volume1/@appstore/PHP82/usr/bin/php /usr/local/bin/composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（群晖场景） - 宝塔环境则用
sudo -u www /www/server/php/82/bin/php /usr/local/bin/composer config -g ... - 检查目标用户家目录是否存在
.composer：若无，先sudo -u admin mkdir -p /var/services/homes/admin/.composer（路径按实际用户 home 调整）
多服务器 PHP 环境不一致，镜像配置可能被绕过
镜像源只在 Composer 请求包时生效；如果底层 PHP 不通 HTTPS、缺 openssl 扩展、或 phar.readonly = On，Composer 会退回到直连官方源并报 SSL 错误——此时脚本即使写对了配置也白搭。
- 脚本中必须前置验证：用目标 PHP 路径执行
php -r "file_get_contents('https://mirrors.aliyun.com/composer/packages.json');" - 失败时自动启用扩展：
sudo /usr/syno/bin/synoscgi.cgi 'SYNO.Core.Package.Server' '{"package":"PHP82","action":"enable_extension","extension":"openssl"}'（群晖） - 宝塔用户需调用
/www/server/panel/py/tools.pyc接口或直接改/www/server/php/82/etc/php.ini后重启 PHP
项目级配置优先级高于全局，脚本得兼顾覆盖逻辑
一旦项目根目录存在 composer.json 并定义了 repositories，全局镜像配置就完全失效。批量同步时不能只改全局，还得判断项目是否已锁定源。
- 脚本可加检测：
grep -q '"repositories"' ./composer.json && echo "项目已自定义源，跳过全局配置" - 如需强制统一，脚本应备份原
composer.json，再用jq清空repositories字段（注意保留"packagist.org": false） - 切记：清空后必须运行
composer update --lock，否则旧composer.lock仍指向官方源 ZIP 地址
同步脚本漏掉缓存清理，新镜像不生效
Composer 会缓存 packages.json 元数据，默认不过期。哪怕配置全对、PHP 正常，第一次 composer install 仍可能从旧缓存拉取官方地址的 ZIP 包。
- 脚本末尾必须加：
sudo -u admin /volume1/@appstore/PHP82/usr/bin/php /usr/local/bin/composer clear-cache - 宝塔环境对应路径执行：
/www/server/php/82/bin/php /usr/local/bin/composer clear-cache - 更彻底的做法：删掉
~/.composer/cache目录（但要注意权限归属，避免后续命令因权限拒绝写入）
真正卡住部署的，从来不是镜像 URL 写错，而是脚本在不同服务器上用了不同 PHP 二进制、没切对用户、也没清缓存——三者只要漏一个，composer install 就照旧卡在 Loading composer repositories...。
