必须配置composer/installers和installer-paths映射路径，否则插件仅存于vendor/而WordPress无法识别
如果你直接运行 composer require wordpress/xxx，结果大概率是失败。原因很简单：WordPress的插件并不在Packagist的官方仓库里。想用Composer管理它们，你得走一条“专用通道”——也就是 https://wpackagist.org 这个镜像源。但这还不够，关键在于必须正确配对 composer/installers 和 installer-paths。少了这一步，插件只会安静地躺在 vendor/ 目录下，WordPress后台根本看不见它的踪影。
为什么 composer require wpackagist-plugin/xxx 后插件没出现在后台？
这个问题太常见了，根源几乎都是路径映射没生效。Composer默认会把所有依赖包都装进 vendor/ 文件夹，但WordPress只认 wp-content/plugins/ 这个位置。怎么把插件从“仓库”搬到“前台”呢？这就得靠 composer/installers 这个包来识别类型，再通过 extra.installer-paths 指令进行路径重定向。
排查时，可以按这个顺序来：
- 首先，确认你的
composer.json里已经明确声明了"composer/installers": "^2.0"。这不是可选项，而是必需品。 - 其次，检查
extra.installer-paths配置，必须包含类似"wp-content/plugins/{$name}/": ["type:wordpress-plugin"]的条目。同时，请确保项目根目录下确实存在wp-content/plugins/这个文件夹。 - 然后，运行
composer install -v并仔细观察日志。如果能看到WordPressInstaller::install这样的输出，说明路径映射生效了；如果没这行，那基本就是composer/installers没被触发。 - 最后，还可以检查一下插件包自身的定义。打开
vendor/wpackagist-plugin/akismet/composer.json这样的文件，看看里面有没有"type": "wordpress-plugin"。WPackagist自动同步的包通常都带，但一些手动创建或私有的包很容易遗漏这个关键属性。
wpackagist-plugin/ 包名怎么查才不拼错？
这里有个忠告：千万别凭记忆手敲包名。大小写、连字符、-pro 后缀，甚至是语言变体（比如 polylang 和 polylang-fr），每一个细节都必须严丝合缝。WPackagist并不会保证所有历史版本都在线，一旦拼错，等待你的就是冰冷的 Package not found。
正确的做法是：
- 打开
https://wpackagist.org/网站，直接搜索插件在WordPress官方插件库里的slug。例如，“Classic Editor”的slug是classic-editor。 - 复制搜索结果页面上显示的完整包名，比如
wpackagist-plugin/classic-editor。注意，不是wordpress/classic-editor，也不是单纯的classic-editor。 - 对于付费插件（例如
advanced-custom-fields-pro），同样需要先去WPackagist搜索确认。不要想当然地在免费版名字后面加个-pro了事，因为很多专业版的同步机制和命名规则可能完全不同。
Bedrock 或自定义 webroot 下路径怎么配？
路径配置不是一成不变的。wp-content/plugins/ 只是WordPress的默认结构。如果你用的是Bedrock这样的现代化启动框架，路径可能是 web/app/plugins/；有些项目为了安全，会把核心文件放在 public/ 目录下，路径就变成了 public/wp-content/plugins/。映射路径必须与你的Web服务器实际设置的DocumentRoot完全一致，否则PHP会找不到文件，后台的插件列表自然就是一片空白。
具体调整方法如下：
- 如果你的项目结构是Bedrock风格的，那么
installer-paths就应该写成："web/app/plugins/{$name}/": ["type:wordpress-plugin"]。 - 如果Web服务器（比如Nginx或Apache）配置的root是
/var/www/html/public，那么对应的路径就应该是public/wp-content/plugins/{$name}/。 - 修改完
composer.json后，一个稳妥的做法是先删除vendor/目录和composer.lock文件，然后再运行composer install。这样可以彻底避免旧缓存的干扰。
最后，还有一个极其容易被忽略的“隐形杀手”：文件权限。即便路径完全正确，如果 wp-content/plugins/ 目录的权限或所属用户不允许Web服务器进程（通常是www-data或nginx用户）读取，WordPress也会静默地跳过加载，而且不会抛出任何错误。务必在终端执行 ls -ld wp-content/plugins 检查一下，确保目录的所有者和权限设置得当（例如，不是 root:root，且权限至少为 755）。
