wpackagist.org 是唯一靠谱的 wordpress composer 集成方案，因其提供结构适配而非下载加速，需配合 composer/installers 和正确的 installer-paths 配置才能将插件正确部署到 wp-content/plugins/ 目录。
Composer 本身没有“中文镜像”这个概念，wpackagist.org 也不是加速镜像，而是结构适配器——它把 WordPress.org 的插件/主题 ZIP 包转成 Composer 可识别的包，并预设 type 字段。所谓“中文团队快速部署”，关键不在语言，而在路径、类型和激活逻辑是否对齐。
为什么 wpackagist.org 是唯一靠谱的选择
国内用户常误以为要搭私有镜像（如 Satis）或改 Packagist 源来“加速”，但实际问题根本不在下载速度：
-
wpackagist.org每日自动同步全量插件/主题，所有包都已带"type": "wordpress-plugin"，无需手动 patch 每个包的composer.json - 自建镜像需维护同步、签名、缓存更新，成本远高于收益；而
wpackagist.org在国内访问通常比packagist.org更快且无认证墙 - 它不提供“下载加速”，但能避免
vendor/下堆积一堆未映射路径的冗余文件——这才是部署卡点
必须配 installer-paths，否则插件永远进不了 wp-content/plugins/
只加 wpackagist.org 仓库，composer require wpackagist-plugin/advanced-custom-fields 后文件默认落在 vendor/wpackagist-plugin/advanced-custom-fields/，WordPress 完全看不到——因为没走安装器路由。
- 先运行
composer require composer/installers:^2.0（不是可选，是必需） - 在
composer.json的extra段写死路径映射："wp-content/plugins/{$name}/": ["type:wordpress-plugin"] - 路径中不能写
web/app/plugins/这类 Bedrock 结构，除非你同时用了 Bedrock 的wp-config.php重定向逻辑 - 插件名含破折号（如
wp-mail-smtp），目录名就是wp-mail-smtp/，和后台显示一致
私有插件或付费插件的 type 必须显式声明
自己写的插件或 ACF Pro 这类付费插件，若想被 composer/installers 正确投递，composer.json 里必须带 "type": "wordpress-plugin"。它只看这个字段，不分析文件结构。
- 用 Git 引入私有插件（
"type": "vcs"）时，远程仓库的composer.json也得有正确type - 漏掉
type，插件会被当成普通 PHP 库装进vendor/，不会触发路径映射，也不会出现在后台列表 - 付费插件需配合
auth.json私有仓库认证，但type字段仍要设为wordpress-plugin，否则路径错位
中文团队别碰包名和路径，用注释+脚本替代
Composer 不支持中文包名或路径：写 composer require wpackagist-plugin/中文插件 直接报 Invalid package name；"wp-content/plugins/中文名称/" 在部分 Linux 服务器上会导致解压失败或目录不可读。
- 在
composer.json的comments字段加中文注释："wpackagist-plugin/woocommerce": "^8.0" // WooCommerce:电商插件 - 维护一份本地
plugins-zh.md，对照列出 slug 和中文功能说明（如wp-mail-smtp → 邮件发送） - CI/CD 脚本里用中文日志输出（如
echo "✅ 正在部署「高级自定义字段」插件"），但执行命令仍是纯英文 - 最常踩的坑不是语言，而是：没配
installer-paths、wp-content/plugins/权限不足、插件主文件头缺失或钩子未抽离
真正卡住部署的，从来不是“中文”或“镜像”，而是 installer-paths 是否生效、type 是否声明、路径是否存在且可写——这些细节一旦错位，插件就只是硬盘上的静态文件，不会注册钩子，也不会响应激活操作。
