应在 composer.json 顶层使用 abandoned 字段声明弃用，值为 true、替代包名或 false；extra.deprecated 不被 Composer 识别，无效。

如何在 composer.json 中声明包已弃用

当一个 Composer 包不再维护或被新包替代时，应在 composer.json 的 extra 或顶层字段中明确标记弃用状态。Composer 本身不提供专用字段，但支持通过 abandoned 字段触发安装时警告——这是最直接、用户感知最强的方式。

• abandoned 必须是字符串，可填 true（表示完全废弃）、另一个包名（如 "vendor/new-package"，表示迁移目标），或 false（不推荐，仅用于覆盖父包设置）
• 该字段应放在 composer.json 顶层，**不能**写在 extra 或 autoload 下
• 一旦设置，所有执行 composer install 或 composer update 的用户都会看到类似 Package vendor/old-package is abandoned, you should avoid using it. Use vendor/new-package instead. 的警告

{
    "name": "vendor/old-package",
    "version": "1.2.0",
    "abandoned": "vendor/new-package",
    "require": { ... }
}

为什么 extra.deprecated 不起作用

部分开发者误以为在 extra 中加 "deprecated": true 或类似字段能触发警告，但 Composer 官方**不识别该键**。它不会报错，也不会输出任何提示，纯属无效配置。

Gitguard Skill

Git 安全扫描与仓库健康审计 — 基于熵的密钥检测、复合健康评分、提交质量分析、陈旧分支清理以及依赖扫描

下载

• Composer 只认顶层 abandoned 字段（自 1.0 起支持）
• extra 是供插件或自定义脚本读取的自由区，Composer 核心逻辑完全忽略其中的 deprecated
• 若想在安装后额外提醒，需自行写 scripts 钩子（例如在 post-install-cmd 中 echo 提示），但这无法阻止他人继续 require 该包

弃用警告对依赖树的影响

警告只在当前包被直接或间接安装时出现，不影响解析和安装流程。但要注意几个实际影响点：

• 如果项目根 composer.json 中 require 了已标记 abandoned 的包，警告会立即显示；但如果只是某依赖的子依赖被弃用，警告仍会出现，只是层级更深
• GitHub/GitLab 等平台在 Packagist 同步后，会将 abandoned 状态同步到包页面，显示“Abandoned”徽章，影响用户信任度
• 某些 CI 工具（如 PHPStan + composer-unused 插件）可结合该字段做静态检查，但需额外配置，非默认行为

发布弃用版本前的关键检查项

发版前漏掉以下任一环节，可能导致警告不生效或误导用户：

• 确认 abandoned 值拼写准确：包名必须与 Packagist 上注册的全名一致（含 vendor 名），大小写敏感
• 确保新包已存在且可正常 composer require，否则提示中的 “Use xxx instead” 会变成空洞指引
• 如果旧包还有未合并的 PR 或安全修复，应先发一个最终维护版（如 1.2.1），再在 1.2.2 中加入 abandoned 字段并发布
• 不要删 GitHub 仓库或设为 private —— Packagist 依赖公开源码地址同步元数据，私有化会导致同步失败，abandoned 不会生效

弃用不是加个字段就完事；真正起作用的前提是 Packagist 成功抓取到新版本的 composer.json，而这个过程有时会有缓存延迟，建议发布后等 5–10 分钟再验证警告是否出现。