必须配置composer/installers和installer-paths映射路径，否则插件仅存于vendor/而WordPress无法识别；包名须严格按https://wpackagist.org/搜索结果复制，大小写、连字符、-pro后缀等均不可错；路径需匹配实际webroot结构，且wp-content/plugins/权限须为755并允许Web进程读取。
直接 composer require wordpress/xxx 肯定失败——WordPress 插件不在 Packagist 官方源里，必须走 https://wpackagist.org 这个镜像源，且要配对 composer/installers 和 installer-paths，否则插件只会躺在 vendor/ 下，WordPress 根本看不到。
为什么 composer require wpackagist-plugin/xxx 后插件没出现在后台？
最常见原因是路径映射没生效。Composer 默认把所有包装进 vendor/，而 WordPress 只从 wp-content/plugins/ 加载插件。你得靠 composer/installers 的 type 识别 + 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没触发 - 检查插件包自身的
composer.json（比如vendor/wpackagist-plugin/akismet/composer.json），它必须含"type": "wordpress-plugin"；WPackagist 自动生成的包都带，但手写或私有包容易漏
wpackagist-plugin/ 包名怎么查才不拼错？
别凭印象手敲，大小写、连字符、-pro 后缀、语言变体（如 polylang vs polylang-fr）全要严丝合缝。WPackagist 不保证所有历史版本都在线，拼错就 Package not found。
- 打开
https://wpackagist.org/，搜索插件在 wordpress.org 上的 slug（比如 “Classic Editor” → slug 是classic-editor） - 复制页面上显示的完整包名：
wpackagist-plugin/classic-editor，不是wordpress/classic-editor或classic-editor - 付费插件（如
advanced-custom-fields-pro）也得去 wpackagist 搜，别默认用免费版名字加-pro猜——有些 pro 版根本不同步
Bedrock 或自定义 webroot 下路径怎么配？
路径不是固定写死的。wp-content/plugins/ 是默认结构，但 Bedrock 用 web/app/plugins/，有些项目用 public/wp-content/。映射必须跟你 Web 服务器实际 DocumentRoot 一致，否则 PHP 找不到文件，后台列表空着。
- 若项目结构是
web/app/plugins/，installer-paths就得写成"web/app/plugins/{$name}/": ["type:wordpress-plugin"] - Web 服务器配置的 root 是
/var/www/html/public，那路径就得对应public/wp-content/plugins/{$name}/ - 改完
composer.json后，先删掉vendor/和composer.lock，再跑composer install，避免旧缓存干扰
最容易被忽略的是：插件安装后，wp-content/plugins/ 目录权限和所属用户必须允许 Web 进程读取，否则即使路径对了，WordPress 也会跳过加载——它不报错，只是静默忽略。检查 ls -ld wp-content/plugins，确保不是 root:root 且权限至少为 755。
