依赖迁移必须通过composer update或require触发解析与重锁，否则lock不更新导致环境不可复现；盲目update会升级所有包，应聚焦目标如composer update vendor/package --with-dependencies --dry-run，并验证PHP/扩展兼容性及自动加载生效。
直接修改 composer.json 中的依赖版本号不是迁移，而是硬编码风险；真正的“依赖迁移”必须通过 composer update 或 composer require 触发解析与重锁，否则 composer.lock 不会更新，环境就不可复现。
用 composer update 精准控制迁移范围
盲目运行 composer update 会升级所有包，极易引入意外变更。迁移应聚焦在明确目标上：
- 只更新某一个包及其可传递依赖：
composer update vendor/package-name - 同时更新多个包（如框架 + ORM）：
composer update laravel/framework doctrine/orm - 加
--with-dependencies确保上游包的子依赖也同步适配新约束 - 加
--dry-run先预览变更，避免误操作（Composer 2.5+ 支持）
迁移前必须验证 PHP 和扩展兼容性
很多迁移失败根本不是版本冲突，而是目标包根本不支持当前运行环境：
Pandas 配置文件报告生成器
下载
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 运行
composer show vendor/package-name查看其requires.php字段，确认是否匹配你的 PHP 小版本（如^8.3不等于8.3.0） - 检查必需扩展是否启用：
php -m | grep -E 'mbstring|openssl|curl|json' - 若目标包依赖
ext-gd但未启用，composer update会静默跳过安装，后续运行时报Class not found
避免手动编辑 composer.json 后直接 install
这是最常被忽略的破坏性操作：改了 require 却不触发解析，会导致 vendor/autoload.php 缺失类映射、composer.lock 版本与实际安装不一致。
- 正确做法永远是：改完
composer.json→ 运行composer update vendor/package-name（或composer install，仅当 lock 文件已含新版本时） - 如果只是想降级某个包，不要写死旧版本到
composer.json，而应使用：composer update vendor/package-name --with-dependencies并配合"require": {"vendor/package-name": "1.2.3"}显式锁定 -
composer install只读composer.lock，它不会重新解析约束——所以迁移动作必须由update或require发起
真正容易被忽略的是：迁移后没验证自动加载是否生效。哪怕 composer update 成功，若包内 autoload 配置有误（比如 PSR-4 命名空间路径错了一级），class_exists() 仍会返回 false。建议迁移后立即跑一句 php -r "require 'vendor/autoload.php'; var_dump(class_exists('Vendor\Package\Client'));" 快速兜底。
