Composer 通过 wpackagist.org 可管理 WordPress 插件，需在 composer.json 中配置 type: "composer" 的仓库 URL 为 https://wpackagist.org，并使用 wpackagist-plugin/{slug} 格式命名包；插件默认装入 vendor/，须配合 wordpress-core-installer 和 installer-paths 才能正确部署到 wp-content/plugins/。

Composer 本身不原生支持 WordPress 插件管理，但通过 wpackagist.org 这个第三方仓库镜像，可以将 WordPress.org 上的插件作为 Composer 包来安装和更新。关键前提是：你必须在 composer.json 中正确配置仓库源，并使用符合 WPackagist 命名规则的包名。

如何配置 wpackagist 仓库

WPackagist 不是 Packagist 官方仓库，必须显式声明为自定义仓库类型 composer，且 URL 必须用 https://wpackagist.org（注意结尾无斜杠）。它不能和默认 packagist.org 混用为同一仓库类型，否则会跳过查找。

• 在 composer.json 的 repositories 数组中添加条目，顺序建议放在 packagist.org 之后（避免意外覆盖）
• 必须指定 type: "composer"，不是 package 或 vcs
• 不要启用 "packagist.org": false，否则连 PHP 依赖也无法装

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    },
    {
      "packagist.org": false
    }
  ],
  "require": {
    "wpackagist-plugin/advanced-custom-fields-pro": "^6.3",
    "php": ">=8.1"
  }
}

插件包名怎么写才有效

WPackagist 的包命名严格遵循 wpackagist-plugin/{slug} 或 wpackagist-theme/{slug} 格式，其中 {slug} 是 WordPress.org 插件页面 URL 的最后一段，不是插件显示名称，也不是 ZIP 文件名。

• https://wordpress.org/plugins/woocommerce/ → 包名是 wpackagist-plugin/woocommerce
• https://wordpress.org/plugins/wp-mail-smtp/ → 包名是 wpackagist-plugin/wp-mail-smtp（注意连字符保留）
• 插件有免费版和 Pro 版时（如 ACF），通常免费版是 wpackagist-plugin/advanced-custom-fields，Pro 版需单独购买 license，wpackagist-plugin/advanced-custom-fields-pro 仅作占位，实际无法自动下载 Pro 文件

为什么 composer install 后插件没出现在 wp-content/plugins/

默认情况下，Composer 把所有包安装到 vendor/ 目录，而 WordPress 要求插件位于 wp-content/plugins/。必须借助插件安装器（如 johnpbloch/wordpress-core-installer）或自定义安装路径规则。

• 先安装 composer require johnpbloch/wordpress-core-installer（它提供了 wordpress-plugin 类型支持）
• 在 composer.json 中为每个插件包声明 "type": "wordpress-plugin"，或全局设置 "extra": {"installer-paths": {"wp-content/plugins/{$name}/": ["type:wordpress-plugin"]}}
• 若用 composer create-project 初始化项目，确保基础骨架已预置好这些配置，否则手动补全后要运行 composer update --lock 刷新锁文件

常见报错与绕过方式

[InvalidArgumentException] Package wpackagist-plugin/xxx not found 最常因三类原因触发：插件名拼写错误、插件刚发布尚未被 WPackagist 抓取（最长延迟 24 小时）、或该插件被作者从 wordpress.org 下架。此时无法通过 Composer 安装。

• 确认插件是否真实存在于 https://www./link/75701c7e77692e6195337368265ab985 页面
• 检查 composer.json 中 repositories 是否拼错 URL（比如多写了 /packages.json 后缀）
• 临时降级方案：用 composer require wpackagist-plugin/xxx:dev-trunk 强制拉取最新开发版（如果存在）
• 长期不可用时，改用 wp-cli plugin install 或直接下载 ZIP 解压，别硬扛 Composer 流程

WPackagist 是个便利层，不是官方保障服务；它的数据同步、版本精度、长期可用性都取决于维护者意愿。生产环境引入前，务必验证插件能否稳定 resolve + install + activate，尤其关注私有插件、需要 license key 的插件，它们天然不在 WPackagist 范围内。