灰度发布不由Composer控制，它仅负责依赖安装与类加载；真正起作用的是运行时决策，如基于用户ID、Header或Nginx透传变量分流请求，并需保障新旧代码共存、数据兼容与缓存隔离。
灰度发布不是靠 Composer 控制的
Composer 是 PHP 的依赖管理工具，只负责安装、更新和自动加载类库，它本身不参与运行时逻辑、不决定请求路由、也不控制流量分发。想用 composer install 或修改 composer.json 来实现灰度发布，注定失败——那只是在本地或部署时拉代码，跟线上流量无关。
真正起作用的是运行时决策：比如根据 Header、用户 ID、IP 或 Cookie 决定走旧版还是新版代码。Composer 能做的，只是帮你把新旧两套逻辑（比如不同版本的业务包）同时装进项目，并确保它们能共存、不冲突。
让不同版本代码共存的关键：autoload 的隔离与版本别名
如果你要灰度测试一个新功能模块（比如 AppPaymentProcessor），又不想改现有调用方，就得让新旧两个实现类同时存在、按需加载。这时候不能简单 require 新包覆盖旧类——会触发 Class 'X' already declared 错误。
- 用
composer require vendor/new-payment-package:^2.0 --no-update先加包，再手动调整autoload配置，避免自动加载冲突 - 在
composer.json中为新包指定自定义 PSR-4 映射，例如："autoload": { "psr-4": { "App\Payment\V1\": "src/Payment/V1/", "App\Payment\V2\": "vendor/vendor/new-payment-package/src/" } } - 运行
composer dump-autoload生效；之后代码里可显式选择new AppPaymentV1Processor()或new AppPaymentV2Processor()
流量切分必须由中间件或网关层完成
PHP 应用自身没有内置的“权重分流”能力。你得在请求入口处插入判断逻辑，常见位置有：
立即学习“PHP免费学习笔记（深入）”；
- Laravel 的
Kernel.php中全局中间件，检查$_SERVER['HTTP_X_USER_ID']或$_COOKIE['gray_flag'] - Swoole HTTP Server 的
onRequest回调里解析请求并设置上下文标识 - Nginx 层用
map指令提取变量，再通过fastcgi_param透传给 PHP（推荐，性能高且与业务解耦）
示例 Nginx 配置片段：
map $cookie_gray_version $use_new_payment {
default "false";
"v2" "true";
}
fastcgi_param GRAY_PAYMENT $use_new_payment;
然后 PHP 中用 $_SERVER['GRAY_PAYMENT'] === 'true' 切分支。
容易被忽略的兼容性陷阱
灰度期间最常出问题的不是逻辑，而是隐式依赖：
- 新旧版本类可能依赖不同版本的同一工具包（如
monolog/monolog），导致composer install报错或运行时报Method not found—— 必须用composer prohibits检查冲突 - 数据库 schema 变更未兼容：新代码读写字段，旧代码报
SQLSTATE[HY000]: General error: 1054 Unknown column—— 灰度前必须保证 DDL 向后兼容（只增不删、字段设默认值） - 缓存 key 命名没带版本号，
cache_key = 'user:'.$id导致新旧逻辑读写互相污染 —— 改成'user_v2:'.$id或加命名空间前缀
灰度不是换包，是换路径+换判断+换数据契约。Composer 只管前半截，后半截全靠你盯住每个接口、每行 SQL、每个缓存键。
