replace字段仅影响依赖解析，不修改自动加载逻辑；平替时须确保接口兼容，否则需配合conflict和provide；本地开发要先移除旧包再引入路径依赖。

replace字段不是autoload的替代品，别把它当路径映射用

很多人看到replace就以为能像autoload一样改类加载路径，结果发现类根本没被加载——replace只影响依赖解析阶段，不修改自动加载逻辑。它本质是告诉Composer：“这个包我已用别的实现覆盖了，请别再装它”。如果你只是想换加载路径，该配autoload或autoload-dev，而不是动replace。

平替废弃库时，必须保证接口完全兼容

比如原库monolog/monolog v1 已废弃，你想用monolog/monolog v2 代替，但v2的Logger构造函数签名变了，这时直接在replace里写"monolog/monolog": "2.0.0"会导致依赖其他v1特性的包运行时报ArgumentCountError。实际操作中要：

• 确认所有调用方代码（包括你自己的和间接依赖的）都不依赖被移除的方法或参数
• 检查目标平替库是否声明了provides（如psr/log-implementation），必要时在replace中一并声明
• 若接口不兼容，得配合conflict阻止旧版本被拉入，再手动升级调用代码

replace + provide 组合才能骗过强约束依赖

有些包硬编码依赖"some/old-package": "^1.0"且没申明provide，光靠replace无法满足其require条件。这时得补上provide：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

{
    "replace": {
        "some/old-package": "self.version"
    },
    "provide": {
        "some/old-package": "2.1.0"
    }
}

注意provide值必须是语义化版本号（不能是dev-main），否则Composer会忽略；而且该版本号要能通过^1.0这类约束校验，否则下游包仍会报错“no matching package found”。

本地开发平替时，vendor路径冲突容易被忽略

用path仓库方式引入本地平替包时，如果replace目标包已在vendor中存在，Composer不会自动删掉它——你得先composer remove some/old-package，再composer require --dev ./local-replacement，否则会出现两个同名命名空间类共存，PHP优先加载vendor里的旧版，导致平替失效。更稳妥的做法是：replace声明后加"minimum-stability": "dev"和"prefer-stable": false，避免Composer因稳定性策略跳过你的本地包。