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.php.cn/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 范围内。
