直接改 composer.json 的 repositories 不够用，因为镜像配置影响元数据解析、版本匹配和插件加载，私有包、path 仓库或自定义插件会静默失败；需全局配置并清理缓存、重生成 autoload 才能确保一致性。
为什么直接改 composer.json 的 repositories 不够用
因为 Composer 的镜像配置不只影响依赖下载，还决定包元数据解析、版本约束匹配、甚至插件加载行为。单纯在 composer.json 里加国内镜像源（比如阿里云或腾讯云），遇到私有包、带 path 类型仓库、或启用了 composer-plugin-api 的自定义插件时，会静默失败——composer install 看似成功，但实际加载的类路径错乱或插件未激活。
- 镜像源只代理
packagist.org公共元数据，不代理私有composer repository的packages.json -
composer config --global repo.packagist composer https://mirrors.aliyun.com/composer/才能覆盖全局解析逻辑 - 若项目已存在
vendor/且含本地path包，迁移前必须先composer dump-autoload --optimize，否则 autoload 仍指向旧路径
如何让 composer.lock 在不同镜像间保持可复现
composer.lock 本身不记录镜像地址，但它的 content-hash 和包的 dist.url 字段受当前镜像响应内容影响。同一份 composer.json，在官方源和阿里云镜像下生成的 lock 文件可能哈希不一致，导致 CI 构建失败。
- 迁移前运行
composer clear-cache，避免本地缓存污染新镜像结果 - 用
COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer update --lock强制指定镜像生成 lock - 检查
lock中每个包的dist.url是否都以镜像域名开头（如https://mirrors.aliyun.com/composer/dists/...），不是则说明部分包仍走默认源
composer create-project 迁移时忽略 vendor 目录的陷阱
很多人用 composer create-project xxx/project ./new-env --no-install 搭新环境，再手动 composer config 改镜像，最后 install。问题在于：--no-install 会跳过插件初始化阶段，某些依赖于 PluginInterface 的包（如 hirak/prestissimo）根本不会注册，后续 install 也补不回来。
- 正确做法是先配置好全局镜像（
composer config --global），再执行create-project，不加--no-install - 若必须分步，需在
install前手动触发插件加载：composer dump-autoload && php -r "require 'vendor/autoload.php';" - 注意
create-project默认会执行post-create-project-cmd脚本，这些脚本若依赖网络请求，也得确保走镜像（改php.ini的curl.cainfo或设HTTPS_PROXY）
一键迁移脚本里必须处理的三个冷门路径
真正“一键”不是只跑几条 composer 命令，而是覆盖开发机到生产机之间所有隐式依赖路径。漏掉任何一个，上线后就报 Class not found 或 Cannot declare class。
立即学习“PHP免费学习笔记（深入）”；
-
vendor/composer/autoload_static.php：这个文件由 Composer 自动生成，但它的$classMap数组依赖于当前vendor/结构。迁移后若目录名变了（比如从project-v1到project-prod），必须重生成：composer dump-autoload --classmap-authoritative -
~/.composer/cache/：不同机器用户家目录不同，缓存内容不一致会导致 hash 计算偏差，脚本开头应加rm -rf ~/.composer/cache/* -
./.env和./config/下的硬编码 URL（如 API 地址、数据库 DSN）：这些和 Composer 无关，但常被误认为“环境迁移已完成”，需单独校验
镜像切换只是迁移链上最显眼的一环，真正的难点藏在 autoload 机制、插件生命周期和路径敏感的缓存行为里。没动过 vendor/ 目录结构的人，最容易在 autoload_static.php 上栽跟头。
