composer update 会升级整个依赖树，极易导致白屏或报错；升级单个扩展需指定名称并确认兼容性，升级后必须执行 setup:upgrade、di:compile 和 cache:clean。
composer update 会升级所有依赖，不是只升扩展
直接运行 composer update 会让 Magento 2 整个依赖树重新解析，可能连 php、zendframework 或 magento/framework 都跟着升级，极易导致白屏或报错。升级单个扩展必须锁定范围。
- 只升级指定扩展：用
composer update vendorname/module-name（例如composer update amasty/shopby） - 同时升级扩展及其直系依赖：加
--with-dependencies，但要确认这些依赖是否兼容当前 Magento 版本 - 升级前先看当前版本：
composer show vendorname/module-name，对比 Packagist 上的最新稳定版 - 别在生产环境直接跑
update—— 先在开发环境测试，且确保已备份composer.lock和数据库
升级前必须检查 module 的 Magento 版本兼容性
很多扩展（尤其是付费模块）会限制支持的 Magento 版本范围，比如只支持 2.4.5–2.4.7。Composer 不会主动校验这个，它只认 composer.json 里的 require 声明。一旦装了不兼容版本，setup:upgrade 会失败，错误常是：
Module 'Vendor_Module' requires component 'magento/framework' 103.0.7 but 103.0.6 was found- 打开扩展的
composer.json，重点看require下的magento/framework和magento/module-store版本约束 - 执行
composer show magento/framework查当前框架版本 - 若扩展要求
^103.0.7，而你的是103.0.6，得先升级 Magento 核心，或降级扩展到兼容版 - 有些厂商把兼容信息写在 README 或 release notes 里，别只信 Packagist 上的 latest tag
升级后必须执行的三步命令缺一不可
只跑 composer update 不等于扩展就生效了。Magento 2 的模块加载机制依赖文件系统扫描 + 数据库注册 + 缓存重建，漏一步就会报 class not found 或后台看不到配置项。
-
bin/magento setup:upgrade—— 注册新模块、更新数据库 schema 和 data patch -
bin/magento setup:di:compile—— 重新生成代理类、插件、工厂等，尤其 PHP 8+ 环境下这步失败很常见（注意内存限制） -
bin/magento cache:clean—— 清掉 config/layout/block_html 等缓存；如果启用了cache:flush，也建议顺手执行 - 如果扩展含静态资源（JS/css），还得补上
bin/magento setup:Static-content:deploy -f（开发模式可跳过，但 CI/生产必须）
vendor 目录权限和 SElinux 可能导致 update 失败
在 centos/RHEL 服务器上，即使 Composer 报错 Could not delete ... 或 file_put_contents 权限拒绝，也不一定是 chmod 777 能解决的。SELinux 的布尔值常被忽略。
- 先确认
vendor/所属用户与 Web 服务（如 nginx/apache）和 CLI 用户一致，避免混合权限 - 临时关闭 SELinux 测试：
setenforce 0；若此时composer update成功，说明是策略问题 - 永久修复：运行
chcon -R -t httpd_exec_t vendor/（apache）或chcon -R -t httpd_sys_rw_content_t vendor/（需读写） - 某些主机禁用
proc_open或exec，会导致 Composer 无法调用 git/unzip，错误类似Failed to download ... no zip extension—— 检查php -m | grep zip和disable_functions
扩展升级不是“换包重启”那么简单。最常卡在版本锁冲突和 post-install-cmd 脚本失败上，遇到报错别急着重试，先看 composer update -v 的详细输出，重点扫一眼 “Conclusion” 行 —— 那里写着 Composer 为什么拒绝安装。