唯一可靠路径是用composer install+完整composer.lock+统一平台声明+私有源凭据；因vendor含硬编码路径、符号链接、平台相关产物，直接复制必致Class not found或版本错乱，镜像源仅提速不改依赖解析。
迁移 PHP 项目时，不能靠复制 vendor/ 或手动同步镜像源配置来保证依赖一致；唯一可靠路径是：用 composer install + 完整提交的 composer.lock + 统一平台声明 + 正确的私有源凭据。
为什么不能直接复制 vendor/ 或改镜像源来“同步”
Composer 不设计为“拷贝即用”。vendor/ 目录里混杂了 autoloader 映射、classmap 缓存、符号链接（如本地路径包）、甚至平台相关扩展检查逻辑。直接复制到另一台机器，大概率触发 Class not found、Cannot redeclare function 或静默加载错版本。
改镜像源（比如把 packagist.org 换成阿里云镜像）本身不解决 lock 文件内容一致性问题——composer.lock 记录的是 dist URL 和校验和，不是源地址。你换镜像后 install 仍会从 lock 里写的原始 URL 下载（除非镜像做了透明代理），而私有包的 URL 更不会自动替换。
- 镜像源只影响下载速度和可用性，不改变依赖解析结果或 lock 文件结构
-
composer config --global repo.packagist composer https://mirrors.aliyun.com/composer/是全局设置，但对私有 VCS 包无效 - 若
composer.lock里某包的dist.url是https://api.github.com/...，换镜像后 Composer 仍会尝试访问它，而非走镜像
composer.lock 必须存在且未被修改
这是 composer install 能“还原快照”的前提。缺失或被意外修改，install 会自动退化为 update 行为，导致版本漂移。
立即学习“PHP免费学习笔记（深入）”；
- 检查命令：
ls -la | grep composer.lock；确认它没被.gitignore排除（常见误配：*lock*） - 新项目首次迁移，若只有
composer.json没有composer.lock，必须回原环境运行composer update --lock补全，再提交 - Git 合并冲突时不要手动编辑
composer.lock，用git checkout --ours composer.lock或--theirs选一方，再composer install验证是否能装通
platform 字段决定 lock 是否能在目标环境生效
composer.lock 顶部的 platform 字段（如 "php": "8.1.0"）不是建议，而是依赖解析时的“虚拟环境”。如果目标机器 PHP 版本低于该值，或缺少 ext-json 等声明的扩展，Composer 会跳过部分包，甚至报 Your requirements could not be resolved。
- 统一声明方式：
"config": {"platform": {"php": "8.1.0", "ext-gd": true}}，写进composer.json根节点 - Windows 和 Linux 对
ext-sockets、ext-posix默认状态不同，若项目依赖它们，必须在platform中显式模拟，否则 CI 成功、本地失败 - 验证命令：
php -v和php -m | grep gd，比只看composer.json的require更准
私有包拉取失败的硬性卡点
composer.lock 里若含 GitLab、Satis、本地路径等私有源包，composer install 会严格按 lock 记录的 URL 和类型拉取，但不会帮你处理权限或 fallback。
- 报
Cloning into ''或401 Unauthorized：说明缺认证，需在项目根目录放auth.json，内容为{"http-basic": {"gitlab.example.com": {"username": "token", "password": "PAT_abc123"}}} - 报
Could not find a matching version of package xxx：目标源中根本不存在该包，或 URL 已失效；不要用--repository-url临时覆盖，除非值是合法 JSON，例如{"type":"vcs","url":"https://gitlab.example.com/php/shared-utils.git"} - 避免 SSH URL（如
git@gitlab.example.com:），CI 环境通常没配 SSH key；HTTPS + PAT 更可控
真正容易被忽略的，是 platform 声明和私有源凭据这两层——它们不报错在 lock 文件生成时，却会在迁移后的第一次 install 中突然暴露，而且错误信息往往不指向根源。
