直接用 composer require 安装 WordPress 插件失败，因默认下载至 vendor/ 而非 wp-content/plugins/；必须配置 wpackagist.org 仓库、composer/installers 依赖及 extra.installer-paths 路径映射三者缺一不可。
直接用 composer require 安装 WordPress 插件或主题，99% 的情况会失败——不是命令错了，而是默认根本不会把文件放到 wp-content/plugins 或 wp-content/themes 里。必须靠 composer/installers + wpackagist.org 配合路径映射才能落地。
为什么 composer require wpackagist-plugin/xxx 不生效？
执行 composer require wpackagist-plugin/akismet 后，插件确实被下载了，但默认进的是 vendor/wpackagist-plugin/akismet，而不是 WordPress 能识别的 wp-content/plugins/akismet。WordPress 不会扫描 vendor/ 目录，所以后台看不到插件。
- 根本原因是：Composer 默认只管“下载”，不管“放哪”；WordPress 只认固定路径下的目录结构
-
wpackagist.org只是提供元数据（包名、版本、zip 下载地址），不参与安装逻辑 - 必须显式声明
"type": "wordpress-plugin"，并启用composer/installers才能触发路径重定向
必须配置的三个关键项：repositories / require / extra.installer-paths
缺一不可。少一个，插件就进不了正确目录。
-
"repositories"段必须包含{"type": "composer", "url": "https://www.php.cn/link/a6e79d4197c9f9927b4102dfcc472dcb"}，否则wpackagist-plugin/*包根本找不到 -
"require"中要包含"composer/installers": "^2.0"，这是路径搬运工，没它一切白搭 -
"extra.installer-paths"必须明确写出目标路径，比如："wp-content/plugins/{$name}/": ["type:wordpress-plugin"] - 注意：路径中不能用
./或绝对路径，{$name}是自动替换的插件文件夹名，不是 ZIP 包名
Bedrock 项目和普通 WordPress 项目的路径差异
如果你用的是 Roots/Bedrock，路径规则完全不一样——插件默认进 web/app/plugins/，不是 wp-content/plugins。硬套普通配置会报错或静默失败。
- Bedrock 的
composer.json已预置installer-paths，指向web/app/plugins/{$name}/，不要覆盖它 - 普通项目若手动改成了 Bedrock 结构（比如把 WordPress 放进
web/），但没同步更新installer-paths，插件就会消失在黑洞里 - 检查
wp-config.php是否设置了WP_PLUGIN_DIR或WP_CONTENT_DIR——这些常量会覆盖 Composer 的路径行为
常见报错和绕过陷阱
遇到 Package not found 或插件安装后不显示，先别急着删 vendor/ 重来。
-
composer clear-cache再composer update：wpackagist 的索引有时延迟，缓存可能卡住旧数据 - 插件名写错：不是插件显示名（如 “Query Monitor”），而是插件 ZIP 包名（
query-monitor），查 https://www.php.cn/link/a6e79d4197c9f9927b4102dfcc472dcb 确认 - 运行
composer show wpackagist-plugin/xxx看是否真能解析出版本，不能说明仓库没配对或网络拦截了 wpackagist - Windows 用户注意路径分隔符：
installer-paths里统一用正斜杠/，不要用\
最易被忽略的一点：每次改完 composer.json 的 installer-paths 或 repositories，必须删掉 vendor/ 和 composer.lock，再跑 composer install。增量更新（composer update）不会重新应用路径规则。
