私有仓库迁移必须同步认证配置、包元数据、vcs缓存及服务端钩子逻辑；否则新仓库无法验证身份、拉取源码或触发构建。关键四类数据：auth.json凭据、packages.json元数据索引、cache-vcs-dir缓存目录、.gitlab-ci.yml等构建脚本。
私有仓库服务器迁移不能只复制 vendor 目录或简单导出包 ZIP，必须同步认证配置、包元数据、VCS 缓存及服务端钩子逻辑；否则新仓库无法验证身份、拉取源码，或触发构建失败。
迁移前必须导出的 4 类关键数据
私有仓库（如 Satis、Private Packagist、GitLab Composer Registry）不是静态文件服务器，它的状态由多层组成：
-
auth.json：含所有 HTTP Basic / Bearer Token 凭据，composer config --global http-basic.example.com token user生成的内容必须导出，否则新服务器无法访问私有包 - 包元数据索引（如 Satis 的
packages.json或 Private Packagist 的 API 导出快照）：仅备份 Git 仓库本身不够，Composer 客户端依赖这个 JSON 去发现版本和 dist URL - VCS 缓存目录（
cache-vcs-dir）：若旧服务器启用了"type": "git"包，且已缓存过github.com/xxx/repo.git的克隆副本，迁移时需一并复制该目录，否则首次composer install会重新 clone —— 在无外网或限速环境下极慢甚至失败 - 服务端钩子与构建脚本（如 GitLab CI 的
.gitlab-ci.yml、Satis 的build.sh）：私有包常依赖 post-install-cmd 构建前端资源或生成配置，漏掉这些，vendor/bin下的可执行文件可能缺失或损坏
新服务器上如何重置 Composer 认证
直接拷贝 ~/.composer/auth.json 到新机器不可靠：路径硬编码、权限错误、token 过期风险高。应使用命令式重置：
- Linux/macOS：运行
composer config --global http-basic.gitlab.example.com "token" "username"（注意双引号包裹 token，避免 shell 特殊字符截断） - Windows PowerShell：用
composer config --global http-basic.gitlab.example.com $env:GITLAB_TOKEN "username"，确保$env:GITLAB_TOKEN已预设且未被日志记录 - 若私有仓库使用 OAuth2 Bearer Token（如 GitHub Packages），改用
composer config --global bearer.github.com "your-token-here" - 验证是否生效：
composer global config --list | grep -A2 "http-basic"，输出应显示完整域名和脱敏后的用户名
为什么不能跳过 composer.lock 直接 composer update
迁移私有仓库时，很多人误以为“只要新服务器能连上私有源，composer update 就能拉最新版”，这是危险操作：
-
composer.lock锁定的是每个包的dist.shasum和source.reference，而私有包的 dist ZIP 往往由服务端动态生成（如 Satis 打包dist/子目录）。update会忽略 lock 文件里的哈希，强制重新解析并下载——若新仓库尚未完成全量 rebuild，就会报Package not found - 私有包常含
replace或provide字段用于替代官方包（如"monolog/monolog": "dev-private-fix as 2.10.0"），update可能因版本约束宽松而选错分支，导致类名冲突或方法不存在 - 正确做法：在新服务器上先确认私有源可用（
composer show vendor/private-package），再运行composer install—— 它严格按 lock 文件匹配，失败即止，不尝试降级或升版
Git 类型私有包的 VCS 缓存必须单独迁移
Composer 对 "type": "git" 的包不做 dist 缓存，而是把整个 Git 仓库 clone 到 cache-vcs-dir 下的子目录。这个路径不随 COMPOSER_CACHE_DIR 自动推导，必须显式配置：
- 查旧服务器当前值：
composer config --global cache-vcs-dir，典型输出如/home/user/.composer/cache/vcs - 在新服务器创建相同路径：
mkdir -p /home/user/.composer/cache/vcs，然后完整复制旧机对应目录内容（保留github.com/xxx/repo.git/结构） - 再执行一次配置命令：
composer config --global cache-vcs-dir "/home/user/.composer/cache/vcs"，否则 Composer 仍查默认路径 - 验证方式：
composer install -v输出中若出现Cloning into '/home/user/.composer/cache/vcs/github.com-xxx-repo.git'，说明没生效；若直接显示Using version x.x.x for vendor/package且无 clone 日志，则成功复用缓存
私有仓库迁移最易被忽略的点是服务端构建逻辑与客户端缓存的耦合性——你复制的不是代码，是一套带状态的交付流水线。哪怕 Git 仓库地址没变，只要 VCS 缓存路径或 auth 配置差一个字符，composer install 就可能从“秒级完成”退化为“半小时反复失败”。
