Composer require不能直接装WordPress主题，因wordpress.org非Composer仓库，必须配置wpackagist.org仓库、composer/installers依赖及extra.installer-paths路径映射，并确保包type为wordpress-theme，否则主题将落入vendor/而不可见。
composer require 不能直接装 WordPress 主题，必须先让 Composer 知道从哪找、怎么装、装到哪——否则不是报 Could not find package，就是装完在 vendor/ 里，后台根本看不到。
为什么 composer require wordpress/theme-name 一定失败？
WordPress 官方主题目录（wordpress.org/themes/）不是 Composer 仓库，Packagist 也不收录这些包。Composer 默认只查 packagist.org，对 wordpress.org 的主题一无所知。
-
wpackagist-theme/twentytwentyfour是正确格式，wordpress/twentytwentyfour或twentynineteen都会失败 - WPackagist 是镜像服务，它把 wordpress.org 的主题元数据转成 Composer 可识别的包，但不托管代码本身
- 必须显式在
composer.json的repositories里加一行：{"type": "composer", "url": "https://wpackagist.org"}
主题装不进 wp-content/themes/？检查这三处
装完发现主题文件在 vendor/wpackagist-theme/twentytwentyfour/，后台空白——说明路径映射没生效。核心依赖和配置缺一不可：
- 已运行
composer require composer/installers:^2.0（^1.x不支持wordpress-theme类型） -
composer.json的extra.installer-paths包含："wp-content/themes/{$name}/": ["type:wordpress-theme"] - 所装主题包的
composer.json中"type"值必须是wordpress-theme（WPackagist 自动生成的包都满足，手动注册的 package 类型需自己写）
用 type: vcs 装自建或 GitHub 主题时的坑
私有主题、开发中主题或非 WPackagist 收录的主题，推荐用 Git 仓库方式引入。但 vcs 不像 wpackagist 那样自动带类型，容易漏关键配置：
- 在
repositories里声明时，type必须是vcs，url指向 GitHub/GitLab 仓库 HTTPS 地址 - 目标仓库的
composer.json中必须有"type": "wordpress-theme"，否则installer-paths规则不匹配 - 版本别名要用
dev-main或1.2.3，别写master（Composer 8+ 已弃用） - 如果主题依赖其他 Composer 包（如 Twig），确保其
autoload配置正确，否则启用时可能报Class not found
更新主题后前台白屏或样式错乱？先看这个
Composer 更新主题只是替换文件，不触发 WordPress 的“激活逻辑”。尤其主题含 functions.php 初始化代码、依赖特定 PHP 扩展或要求数据库变更时，容易出问题：
- 更新后务必进后台「外观 → 主题」手动启用一次，强制触发
switch_theme钩子 - 若主题含
theme-update-checker或自定义更新机制，确认它没覆盖 Composer 的版本控制逻辑 - CI/CD 部署时，别只跑
composer install：要加wp theme activate {$name}（需 WP-CLI）或确保部署脚本包含主题激活步骤
setup_theme 钩子只在切换时跑一次。路径对了，类型对了，仓库对了，最后一步手动激活——这个动作不在 Composer 职责范围内，但缺它整个流程就断在最后一厘米。 
