应使用 Composer 的 path 仓库机制替代 composer link：在主项目 composer.json 中配置 repositories 为 path 类型并指定本地包路径，require 中引用 dev 分支，运行 composer update 更新 composer.lock，新环境执行 composer install 即可自动重建软链接。
composer link 生成的软链接不能直接迁移
软链接（symbolic link）本身不包含包内容，只记录路径。把整个 vendor/ 目录复制到新服务器后，vendor/package-name 指向的仍是旧机器上的 ../my-local-package，路径失效导致 Class not found 或 failed to open stream。
常见错误现象：
- 运行
php artisan tinker或composer dump-autoload报错找不到类 -
ls -la vendor/package-name显示目标路径为红色（broken link） -
composer install后软链接消失，被替换成正常下载的包
迁移前必须导出本地包的真实状态
软链接只是开发期临时手段，不是可部署状态。要让本地修改能跨环境还原，得用 Composer 原生支持的 path 仓库机制，它会写入 composer.lock 并生成可复现的符号链接。
操作步骤：
- 确认本地包根目录下有合法
composer.json（含name、version、autoload） - 在主项目
composer.json的repositories数组里加一项："repositories": [<br> { "type": "path", "url": "../my-local-package" }<br>] - 把依赖从版本号改为分支名，例如：
"vendor/my-local-package": "dev-main" - 运行
composer update vendor/my-local-package（必须带包名，避免全量更新） - 检查
composer.lock是否已记录该包的type: "path"和真实路径
新服务器上恢复 path 类型软链接的关键动作
只要 composer.json 和 composer.lock 齐全，且本地包路径结构一致，composer install 就会自动重建软链接——但前提是路径存在、权限可读、PHP 扩展齐全。
容易忽略的点：
-
url是相对路径，迁移后需确保主项目与本地包的相对位置不变（如都放在/var/www/project和/var/www/my-local-package） - 新服务器上执行
composer install前，先ls -l ../my-local-package确认目录可访问 - 若报
Could not parse version constraint，说明本地包的composer.json缺version字段或格式非法 - 别加
--no-dev——path类型包默认归为 dev 包，加了会跳过安装
为什么不用 composer link + rsync 迁移？
因为 composer link 不改 composer.lock，也不注册仓库，纯属运行时快捷方式。它绕过了 Composer 的依赖解析和锁定机制，导致：
- 新环境运行
composer install时完全感知不到这个链接，按composer.lock正常拉取发布版 - 手动
composer link需全局插件支持（Composer 2.4+ 内置），旧版本直接报 command not found - 后续
composer update会无条件覆盖软链接，且不会警告 - CI/CD 流水线无法复现，因缺乏声明式配置
真正可迁移的只有声明（composer.json 中的 repositories + require）和锁定（composer.lock），其余都是临时状态，不该进备份清单。
