直接 composer require wordpress/plugin-name 必然失败，因 wordpress 插件不在 packagist 官方源，必须配置 wpackagist.org 仓库、composer/installers 依赖及 extra.installer-paths 路径映射三者缺一不可；包名须为 wpackagist-plugin/{slug}，路径需匹配实际结构，且插件主文件须含标准头注释并手动激活。
直接 composer require wordpress/plugin-name 必然失败——WordPress 插件不在 Packagist 官方源里，必须走 https://wpackagist.org 镜像源，且要配对 composer/installers 和 extra.installer-paths，否则插件只会躺在 vendor/ 下，WordPress 根本看不到。
为什么 composer require wpackagist-plugin/xxx 报 “Package not found”？
这不是包名拼错，而是 Composer 根本没去 wpackagist.org 查。它默认只认 packagist.org，你得手动告诉它“去哪找”。
-
composer.json里必须显式添加repositories配置，type必须是composer（不是vcs或package） -
url必须写全："https://wpackagist.org"，少个s、协议写成http或漏掉斜杠都会失效 - 包名必须严格按
wpackagist-plugin/{slug}格式，比如https://wordpress.org/plugins/classic-editor/的 slug 就是classic-editor，完整包名是wpackagist-plugin/classic-editor，不能手写成wordpress/classic-editor - 付费插件如
advanced-custom-fields-pro，也得去wpackagist.org搜，别凭印象加-pro后缀猜——有些 pro 版根本不同步
installer-paths 映射不生效，插件还是进了 vendor/
映射失效最常见原因不是配置漏了，而是驱动没装或没触发。
- 先确认已执行
composer require composer/installers:^2.0——这不是可选依赖，是必需扩展 -
extra.installer-paths的键值必须匹配实际路径结构：例如你的 WordPress 根目录下是wp-content/plugins/，就写"wp-content/plugins/{$name}/": ["type:wordpress-plugin"]；如果是 Bedrock 结构，路径就得是web/app/plugins/{$name}/ - 运行
composer install -v，看日志里是否出现WordPressInstaller::install——没这行，说明composer/installers完全没接管安装流程 - 检查目标插件包自身的
composer.json（比如vendor/wpackagist-plugin/akismet/composer.json），它必须含"type": "wordpress-plugin"；WPackagist 自动生成的包都带，但私有包或手写包容易漏
插件装进 wp-content/plugins/ 了，后台却看不到
路径对了只是第一步，WordPress 要扫描并识别插件，还得满足运行时条件。
-
wp-content/plugins/目录必须真实存在，且 Web 进程（如www-data、nginx）有读取权限（至少755） - 插件主文件（如
wp-content/plugins/akismet/akismet.php）必须包含标准插件头注释，否则 WordPress 不会把它当插件处理 - Composer 只管文件落地，不负责激活；需用
wp plugin activate akismet（WP-CLI）或后台手动启用 - 更新插件时注意版本格式：WPackagist 的版本号来自 WordPress.org 的 SVN 标签，用的是
12.3或trunk这类标识，不是 Git commit hash；遇到trunk时，composer默认拒绝，得显式用"dev-trunk"或改用"*"约束
真正卡住的地方往往不是配置本身，而是 composer/installers 没触发、路径和 Web 服务器 DocumentRoot 不一致、或者插件主文件缺头注释——这些点不报错，但结果就是“看不见”。
