Composer require 直接装 WordPress 插件常失败，因 Packagist 不收录插件且机制不兼容；需用 wpackagist.org 仓库、正确 type（如 wpackagist-plugin）、配置 extra.installer-paths 指向 wp-content/plugins/，并确保路径存在、权限正确、主文件头规范及依赖激活有序。
为什么 composer require 直接装 WordPress 插件经常失败
因为官方 Packagist 不收录 WordPress 插件，wp-cli 和 wp-admin 的插件安装机制和 Composer 完全不兼容——前者靠 ZIP 下载+文件解压+激活钩子，后者依赖 composer.json 中的 autoload、type、installer-paths 等元信息。直接 composer require wpackagist-plugin/akismet 看似能成功，但实际不会生成可运行的插件目录结构，也不会触发 WordPress 的插件加载逻辑。
- WPackagist 是社区维护的镜像源，它把 WordPress.org 插件页“翻译”成 Composer 可识别的包定义，但不改变 WordPress 本身的加载规则
- 必须配合
wpackagist.org作为仓库 + 正确的type（如wpackagist-plugin）+ 自定义installer-paths - 如果没配
installer-paths，插件会被装进vendor/下，WordPress 根本找不到
怎么让 composer install 把插件放到 wp-content/plugins/
靠 composer.json 里的 extra.installer-paths 告诉 Composer：“这些 type 的包，别放 vendor，往这儿扔”。这是最常漏掉、也最影响结果的一环。
- 在
composer.json的extra字段下加：
"installer-paths": {
"wp-content/plugins/{$name}/": ["type:wpackagist-plugin"],
"wp-content/themes/{$name}/": ["type:wpackagist-theme"]
}
{$name} 是插件原始 slug（比如 advanced-custom-fields-pro），不是包名（wpackagist-plugin/advanced-custom-fields-pro）wp-content/plugins/ 路径，否则 Composer 会静默失败或报错 Could not create directory
web/app/plugins/{$name}/，对应改写 installer-paths
wpackagist-plugin/ 包名怎么查？别手敲
WPackagist 不是所有插件都实时同步，也不是所有版本都保留。手动拼包名极易出错：大小写、连字符、pro 后缀、语言变体（如 polylang vs polylang-pro）全得对上，否则 composer require 找不到包。
- 去
https://wpackagist.org/搜索插件名，复制页面上显示的完整包名（格式一定是wpackagist-plugin/xxx或wpackagist-theme/yyy） - 搜索时用插件在 wordpress.org 上的 slug，比如 “Classic Editor” 对应 slug 是
classic-editor，包名就是wpackagist-plugin/classic-editor - 避免用中文名、带空格名、或插件后台显示的“全称”，那只是 display name，不是机器标识
- 如果搜不到，说明该插件尚未被 WPackagist 收录（常见于新发布、私有、或仅限 .org SVN trunk 的插件）
装完插件，WordPress 还是提示“已损坏”或“无法激活”
这通常不是 Composer 的问题，而是 WordPress 加载机制和文件权限/路径的冲突。Composer 装好了，不代表 WordPress 认得出。
- 检查
wp-content/plugins/下对应插件目录里是否有主插件文件（如akismet/akismet.php），且文件权限为 644，目录为 755 - 确保插件主文件头部注释包含正确格式的 Plugin Name（如
Plugin Name: Akismet Anti-Spam），少一个冒号或换行错位都会导致“已损坏” - 如果插件含
mu-plugins或依赖其他插件（如 ACF Pro 需要 ACF Free），Composer 不会自动处理依赖激活顺序，得自己在wp-config.php或 mu-plugin 中显式启用 - 某些插件（如
woocommerce）本身是type:wordpress-plugin，不是wpackagist-plugin，不能混用源，强行 require 会导致 autoload 错乱
路径、权限、主文件头、激活时机——四个点里只要一个不对，插件就卡在“已安装但不可用”状态。别急着重装，先 ls -l wp-content/plugins/xxx 和 head -20 wp-content/plugins/xxx/xxx.php 看两眼。
