Composer无法直接安装WordPress官方主题，因其缺乏composer.json和Packagist注册；仅支持Git托管且含"wordpress-theme"类型的第三方主题，需配合composer/installers及正确installer-paths配置。
Composer 不能直接管理 WordPress 官方主题目录里的主题（比如从 wordpress.org 主题库一键安装），但能可靠地管理 Git 仓库托管的第三方主题——前提是主题作者提供了 composer.json 并发布到 Packagist 或私有仓库。
为什么 wp-content/themes/ 不能直接用 composer require 装官方主题
WordPress.org 主题库不提供 Composer 包注册机制，其 ZIP 下载页无 composer.json，Packagist 上也不存在 wpackagist/theme/twentytwentyfour 这类自动同步包（wpackagist 已停更多年，不可信）。强行用 package 类型硬写会丢失更新能力、版本约束失效，且每次 composer update 都可能覆盖自定义修改。
可行路径只有两条：
- 主题本身是开源项目，托管在 GitHub/GitLab，作者主动维护
composer.json（例如roots/sage） - 你自行 fork 主题，在其根目录添加合规
composer.json，推送到自己的 Git 仓库并配置为 VCS repository
如何让 Composer 正确安装 Git 托管的主题到 wp-content/themes/
关键不是“绕过 WordPress 机制”，而是让 Composer 知道：这个包应该解压到哪、类型是什么、要不要跳过 autoload。
在项目根目录的 composer.json 中添加：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/username/theme-name"
}
],
"require": {
"username/theme-name": "^5.0"
},
"extra": {
"installer-paths": {
"wp-content/themes/{$name}/": ["type:wordpress-theme"]
}
}
}
注意三点：
需要创建、读取、编辑或处理 Word 文档（.docx / .dotx）时使用。触发词：'Word'、'word 文档'、'.docx'、'生成报告'、'制作合同/简历/方案/说明书'、'提取 word 内容'、'在文档里查找替换'、'给文档加页眉页脚/目录/表格'。也用于把任意内容排版成一份正式的 Word 文件。不要用它处理 PDF、Excel 或无关编程任务。中文创作场景尤其适合：小说大纲稿、投稿文档、合同、简历、工作总结。
- 必须声明
"type": "wordpress-theme"—— 这个 type 是composer/installers插件识别的固定值，不是随便写的 -
installer-paths的路径必须以wp-content/themes/开头，{$name}会自动替换为包名最后一段（如acme/my-theme→my-theme） - 务必运行
composer require composer/installers，否则installer-paths不生效
常见失败现象和对应检查点
执行 composer require username/theme-name 后，主题没出现在 wp-content/themes/，或报错 Could not parse version constraint：
- 检查该 Git 仓库的
composer.json是否包含"type": "wordpress-theme"；没有就加，否则installer-paths规则不匹配 - 检查仓库是否有 Git tag（如
v5.2.0），Composer 默认只认带v前缀的语义化标签；若只有main分支，需显式写"dev-main as 5.3.0" - 检查
composer.json根目录是否真在仓库顶层；如果主题代码藏在/src子目录，Composer 会把整个仓库克隆进来，导致路径错乱 - 运行
composer install -vvv，看输出里有没有Installing username/theme-name (5.2.0)和Extracting archive行；没有说明没找到包，重点查repositoriesURL 是否拼错或私有仓库未配 SSH key
主题更新时要注意的权限与钩子
composer update 会删掉旧目录再解压新版本，如果你在主题里写了自定义 PHP 文件或改了 functions.php，这些改动会被清空。
安全做法只有两个：
- 所有定制逻辑抽离到子主题（child theme），父主题用 Composer 管理，子主题手动放
wp-content/themes/下 - 用
composer-scripts在post-update-cmd里自动 patch 修改（适合 CI 环境），但需额外维护 diff 文件，复杂度陡增
别依赖 git stash 或手动备份——Composer 不感知 Git 状态，它只管文件系统层面的覆盖。
