利用Composer镜像优化WordPress插件开发工作流-composer-PHP中文网

wpackagist.org是最稳定方案，因其每日自动同步全量插件/主题并预设type字段，配合composer/installers和installer-paths配置，可将插件精准安装至wp-content/plugins/，避免vendor冗余；但需手动激活且路径映射必须显式声明。

利用composer镜像优化wordpress插件开发工作流

直接用 wpackagist.org 镜像 + composer/installers 是目前最稳定、兼容性最好的方案，不需要自建镜像源或改 Packagist 默认行为。

为什么 wpackagist.org 比自己搭镜像更实用

社区维护的 wpackagist.org 每天自动同步 WordPress.org 全量插件/主题，所有包都已预设 "type": "wordpress-plugin" 或 "type": "wordpress-theme"，无需手动改每个包的 composer.json。它不是“加速镜像”，而是结构适配器——把 ZIP 包转成 Composer 可识别的包，并映射类型。

自己搭私有镜像（如 Satis）要维护同步逻辑、签名验证、缓存更新，成本远高于收益
国内直接访问 wpackagist.org 通常比访问 packagist.org 更快，且无认证墙问题
它不提供“加速下载”功能，但避免了 vendor/ 下一堆未映射路径的冗余文件

必须配置 installer-paths 才能让插件进 wp-content/plugins

只加 wpackagist.org 仓库，composer require 后插件默认会进 vendor/wpackagist-plugin/xxx，WordPress 完全看不到——因为没走安装器路由。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

先运行 composer require composer/installers
在 composer.json 的 extra 段写清楚路径映射：

"extra": {
  "installer-paths": {
    "wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
    "wp-content/themes/{$name}/": ["type:wordpress-theme"],
    "wp-content/mu-plugins/{$name}/": ["type:wordpress-muplugin"]
  }
}

注意：路径中不能用 web/app/plugins 这类 Bedrock 结构，除非你同时用了 Bedrock 的 wp-config.php 重定向逻辑
如果插件名含破折号（如 wp-mail-smtp），目录名就是 wp-mail-smtp/，和 WordPress 后台激活时显示的名称一致

开发私有插件时，type 必须显式声明

自己写的插件若想被 composer/installers 正确投递，composer.json 里必须带 "type": "wordpress-plugin"，否则它会被当成普通 PHP 库装进 vendor/，不会触发路径映射。

不要依赖 composer/installers 自动推断类型——它只看 type 字段，不分析文件结构
如果你用 Git 仓库方式引入私有插件（"type": "vcs"），也要确保其远程 composer.json 里有正确 type
付费插件（如 ACF Pro）需走私有仓库 + auth.json，但 type 仍要设为 wordpress-plugin，否则路径错位

常见错误：插件装进去了但后台不显示

最常踩的坑不是网络或权限，而是路径和激活状态脱节：

wp-content/plugins/xxx/ 目录存在，但 xxx/xxx.php 文件里没有正确的插件头注释（Plugin Name: 行缺失或格式错误）
插件目录名和主文件名不一致（例如目录叫 my-plugin，但主文件是 plugin.php，WordPress 不识别）
用了 installer-paths 但没删掉旧的 wp-content/plugins/xxx 手动安装残留，导致后台看到两个同名插件入口
composer install 后没刷新 OPcache（尤其启用了 opcache.enable_cli=1 的环境），PHP 仍读缓存中的旧文件列表