Composer conflict字段怎么写 定义包冲突规则说明【文档】

conflict 字段用于声明当前包与哪些其他包互斥，格式为键值对，键是包名（如 monolog/monolog），值是版本约束（如 ^2.0），安装或更新时若匹配则报错阻止。

composer.json 里的 conflict 字段怎么写

conflict 是 composer.json 中用于声明「当前包与哪些其他包互斥」的字段，不是用来解决冲突的工具，而是提前阻止 Composer 安装不兼容的依赖。它在安装或更新时触发错误，防止运行时出问题。

写法是键值对：键为包名（如 monolog/monolog），值为版本约束（如 ^2.0 或 ）。支持所有 Composer 版本运算符：、、>、>=、!=、^、~、*。

• "conflict": { "php": " —— 禁止在 PHP 8.0 以下环境安装
• "conflict": { "guzzlehttp/guzzle": ">=7.0 —— 冲突特定小版本区间
• "conflict": { "laravel/framework": "*" } —— 完全禁止 Laravel（慎用）

什么时候该用 conflict，而不是 require 或 replace

conflict 的核心场景是「已知不兼容，且无法通过代码适配」。比如你的包用了某个库的私有 API，在 v3.2+ 被移除，但 v3.1 又存在安全漏洞——这时不能靠 require 锁版本，而要用 conflict 明确排除危险范围。

• 用 require 表达「我需要什么」；用 conflict 表达「我绝不能和谁共存」
• replace 是声明「我替代了谁」（如 fork 包），不影响安装逻辑；conflict 会直接中断 composer install
• 若冲突只发生在特定扩展启用时（如 ext-redis vs ext-predis），conflict 无能为力，得靠运行时检测

常见错误：为什么写了 conflict 却没报错

最常被忽略的是作用域问题：conflict 只在当前包被安装（或作为依赖被拉入）时生效。如果用户项目里直接 require 了冲突包，而你的包没被加载（比如只是 dev-dependency），那根本不会触发检查。

• 确保你的包实际出现在最终依赖图中（不是仅在 require-dev 里）
• Composer 不会回溯检查已安装包是否违反新加入包的 conflict 规则——只有执行 composer update 或新 install 时才校验
• 写 "conflict": { "myorg/mylib": "dev-main" } 没用：分支名、dev- 前缀、alias 都不参与 conflict 匹配，只认稳定版本号

conflict 和 platform / platform-check 的关系

conflict 可以写 php、ext-*、lib-*，但这部分行为受 config.platform 影响。如果你在根项目设了 "platform": { "php": "8.1.0" }，Composer 会假装运行在 PHP 8.1，导致 "conflict": { "php": " 失效——因为平台声明覆盖了真实环境判断。

• 运行时 PHP 版本冲突，优先用 config.platform-check = true（默认开启），它会在 composer install 后额外校验真实环境
• conflict 中的扩展名（如 ext-mbstring）必须拼写完全一致，大小写敏感，且不支持通配符
• 想让 CI 环境也触发检查？确保没设 COMPOSER_DISABLE_PLATFORM_CHECKS=1

真正容易漏掉的是：冲突规则不会自动传播。A 包 conflict B，B 包 conflict C，不代表 A 和 C 自动互斥——每个包得各自声明。