直接 composer require wordpress/plugin-name 会失败，因为官方 Packagist 不收录 WordPress 插件/主题；需通过 WPackagist 镜像源，配合配置仓库、composer/installers 和 installer-paths 才能正确安装到 wp-content 目录。
Composer 本身不原生支持 WordPress 插件和主题，但通过 WPackagist 可以将它们当作 Composer 包来安装和更新——前提是项目已正确配置为兼容 WordPress 的自动加载与路径映射。
为什么直接 composer require wordpress/plugin-name 会失败？
因为官方 Packagist（packagist.org）不收录 WordPress 官方仓库的插件/主题。WPackagist 是一个镜像服务，它把 wordpress.org/extend/plugins/ 和 wordpress.org/extend/themes/ 中的项目自动同步为 Composer 兼容的包，但需要显式声明仓库源。
- 默认 Composer 配置只查 packagist.org，不查 wpackagist.org
- WPackagist 上的包名格式是
wpackagist-plugin/akismet或wpackagist-theme/twentytwentyfour，不是wordpress/akismet - 没有在
composer.json中配置type和installer-paths，安装后文件不会落到wp-content/plugins/下
如何在 composer.json 中正确配置 WPackagist？
必须同时完成三件事：添加仓库、声明包类型、指定安装路径。缺一不可。
- 在
repositories数组中加入 WPackagist 的 Composer 仓库地址：{"type": "composer", "url": "https://wpackagist.org"} - 在
extra中声明installer-paths，例如把wpackagist-plugin/*装到wp-content/plugins/{$name}/ - 确保已安装
composer/installers（它是路径映射的驱动），否则installer-paths不生效
{
"repositories": [
{
"type": "composer",
"url": "https://wpackagist.org"
}
],
"require": {
"composer/installers": "^2.0",
"wpackagist-plugin/advanced-custom-fields-pro": "^6.3"
},
"extra": {
"installer-paths": {
"wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
"wp-content/themes/{$name}/": ["type:wordpress-theme"]
}
}
}
安装插件时常见路径错乱或权限错误
即使配置正确，仍可能遇到 wp-content/plugins/ 目录不存在、无写入权限，或 Composer 把插件解压到了 vendor/ 下——这说明 composer/installers 没起作用，或 type 字段未被识别。
- 检查插件包的
composer.json是否包含"type": "wordpress-plugin"（WPackagist 自动生成的包都带这个） - 运行
composer install -v查看详细日志，确认是否触发了WordPressInstaller - 确保项目根目录下已有
wp-content/目录，且 Web 服务器用户有写权限；否则 Composer 会静默跳过安装 - 不要手动修改
wp-content/plugins/下的文件后再运行composer update，会导致 checksum 冲突和重装失败
主题更新后样式丢失或子主题失效
WPackagist 主题安装后是“裸主题”，不含 style.css 头部注释以外的任何逻辑，也不处理父主题依赖或子主题激活状态。
- 子主题不能靠 Composer 自动激活，必须手动在 WP 后台启用
- 如果主题依赖特定版本的 WordPress 核心函数（如
wp_get_environment_type()），而你的站点 PHP 或 WP 版本太低，composer update可能成功但前端报错 - 主题更新不会覆盖
functions.php或自定义模板文件——这些应放在子主题中，而非直接修改 WPackagist 安装的主题目录
WPackagist 是个实用的桥接方案，但它不解决 WordPress 运行时的依赖管理，比如插件之间的钩子调用顺序、主题与插件的兼容性校验，这些仍需人工验证。最易被忽略的是：每次 composer install 前，先确认 wp-content 目录结构完整且可写，否则整个流程会在无声中失败。
