群晖上composer install报错90%因cli与webstation php环境不一致，必须用webstation绑定的php路径（如/volume1/@appstore/php82/usr/bin/php）验证版本、启用phar/mbstring等扩展、关闭phar.readonly、指定该路径执行install并配置正确镜像源。
群晖上 composer install 报错，90% 不是 Composer 本身的问题，而是 CLI 环境和 WebStation 绑定的 PHP 环境不一致——你用的 PHP 路径、扩展、php.ini 配置全都不匹配。
确认你用的是 WebStation 实际绑定的 PHP 路径
报错如 Call to undefined function mb_strlen()、PharException: phar is not supported 或 autoload.php is empty，基本都能归因于此。群晖终端里敲 php 默认指向旧版（比如 PHP 5.6），而你的网站跑在 PHP 8.2 上，两者扩展列表、phar.readonly 设置、SSL 证书路径全不同。
- 进 DSM → WebStation → PHP 设置 → 找到你项目绑定的版本（如 PHP 8.2），记下它的
PHP Path（典型值：/volume1/@appstore/PHP82/usr/bin/php） - SSH 登录后，**必须**用这个完整路径验证：
/volume1/@appstore/PHP82/usr/bin/php -v和/volume1/@appstore/PHP82/usr/bin/php -m | grep -E "(phar|mbstring|openssl|curl)" - 如果
php -m输出里缺mbstring或phar，回 WebStation 对应 PHP 版本的「扩展」页勾选，再点「重启该 PHP 版本」（不是重启整个 WebStation）
运行 install 时必须显式指定 PHP 路径
别直接敲 composer install。你装的 composer 是用某个 PHP 路径生成的，但执行时若被系统默认 PHP 加载，就会触发扩展缺失或 Phar 解包失败。
- 进项目根目录后，用 WebStation 的 PHP 路径调用：
/volume1/@appstore/PHP82/usr/bin/php /usr/local/bin/composer install - 如果报
file_get_contents(): SSL operation failed，说明该 PHP 路径的openssl.cafile没设对——去 WebStation → PHP 设置 → 「自定义设置」里加一行：openssl.cafile = /etc/ssl/certs/ca-certificates.crt，再重启该 PHP 版本 - 如果卡在
Loading composer repositories，先运行composer config -g repo.packagist看输出是否为完整 JSON；如果不是，说明镜像没生效，得重配（见下一条）
镜像配置必须满足三个硬条件才生效
composer config -g repo.packagist 命令静默失败很常见：漏掉任意一个条件，Composer 就当没这回事，继续走 packagist.org，且不报错。
- 键名必须是单数
repo.packagist（写成repos.packagist或packagist.org都无效） - 第二个参数必须是字符串
composer（这是 type 值，不是描述，不能省略） - URL 必须是 HTTPS 且以
/结尾：https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（会 404） - 配置后务必验证：
composer config -g repo.packagist输出必须是类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}的 JSON；空、null或报错都说明没落盘 - 如果项目
composer.json里有"repositories"字段（哪怕只是{}），全局镜像会被完全屏蔽——删掉该字段再试
中断后必须清理 vendor 和缓存才能重试
下载一半失败不是网络问题，是本地状态已损坏：缓存 ZIP 截断、installed.json 写入不全、校验失败数据残留，都会让后续所有重试卡在同一位置。
- 遇到
Failed to extract vendor/package-name或unable to open archive，立刻删掉：rm -rf vendor/ composer.lock - 清缓存：
composer clear-cache（注意：必须用同一 PHP 路径执行，否则清理的是另一个用户的缓存） - 再用 WebStation PHP 路径执行：
/volume1/@appstore/PHP82/usr/bin/php /usr/local/bin/composer install - 仍卡住？加
-vvv看真实请求：composer install -vvv 2>&1 | grep "Downloading"，日志里出现的域名才是最终生效源
最常被忽略的一点：群晖的 /usr/local/bin 是只读挂载点，但允许普通用户建软链；如果你曾用 sudo 或 root 身份操作过 composer 或 vendor/ 目录，它们的属主就变成 root，后续普通用户运行会静默失败——别 chmod 777，用 chown -R admin:admin /path/to/project 修复归属。
