直接 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 目录结构完整且可写，否则整个流程会在无声中失败。