怎么通过Composer国内镜像快速搭建WordPress开发环境？

必须配置wpackagist.org仓库、composer/installers及installer-paths映射，否则插件仅存vendor/而WordPress无法识别；包名须严格按wpackagist.org搜索结果复制，路径需匹配webroot且wp-content/plugins/权限为755。

直接用 wpackagist.org + composer/installers，比换 Packagist 镜像更有效。国内访问 wpackagist.org 通常比 packagist.org 更快，且它不是“加速镜像”，而是专为 WordPress 设计的结构适配器——所有插件/主题都已预设 "type": "wordpress-plugin"，省去手动改每个包的 composer.json。

为什么别只换 Packagist 镜像

单纯把 packagist.org 换成阿里云或腾讯云镜像，对 WordPress 插件安装没用：这些镜像只加速 PHP 库下载，不处理 WordPress 插件 ZIP 包的类型识别和路径映射。
你 composer require wpackagist-plugin/akismet 后，插件仍会落在 vendor/wpackagist-plugin/akismet，WordPress 后台根本看不到——因为没走安装器路由。

必须配置 installer-paths

不加这个，composer/installers 就不知道该把插件扔哪。路径映射必须显式声明，且不能写相对路径（如 web/app/plugins），除非你同时用了 Bedrock 的 wp-config.php 重定向逻辑。

• "wp-content/plugins/{$name}/": ["type:wordpress-plugin"] —— 插件名含破折号（如 wp-mail-smtp）时，目录名就是 wp-mail-smtp/，和后台显示一致
• "wp-content/themes/{$name}/": ["type:wordpress-theme"]
• 私有插件也得在自己的 composer.json 里写 "type": "wordpress-plugin"，否则会被当普通 PHP 库装进 vendor/

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

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

• 路径映射漏了 installer-paths 配置，插件实际在 vendor/ 下，WordPress 根本扫描不到
• 插件目录权限不对（比如 wp-content/plugins/xxx 不可读），后台列表为空但无报错
• 插件名和目录名不一致（例如插件主文件是 my-plugin.php，但目录叫 myplugin），WordPress 不认
• 付费插件（如 ACF Pro）没配 auth.json 或 type 字段写错，导致下载失败或路径错位

推荐最小可行配置

初始化项目后，在 composer.json 中确保包含以下三块：

{  "repositories": [    {      "type": "composer",      "url": "https://wpackagist.org"    }  ],  "require": {    "johnpbloch/wordpress": "^6.6",    "composer/installers": "^2.0",    "wpackagist-plugin/akismet": "^5.3"  },  "extra": {    "installer-paths": {      "wp-content/plugins/{$name}/": ["type:wordpress-plugin"],      "wp-content/themes/{$name}/": ["type:wordpress-theme"]    }  }}

执行 composer install 后，插件就真正在 wp-content/plugins/ 下了——但注意：Composer 不负责激活，还得手动或用 wp plugin activate akismet。

复杂点在于，路径映射一旦写错，composer update 会静默覆盖已有目录，而 WordPress 后台不会提示“插件被移走了”，只会消失。所以每次改 installer-paths 前，先备份 wp-content/plugins。