WordPress 主题安装失败：上传限制、权限与常见报错处理
主题装不上，报错原文基本能直接定位到类型。传一半中断是体积限制，传完提示缺 style.css 是包结构不对，解压到一半白屏是内存被打满，让你填 FTP 账号是文件属主不对。四类问题四套改法，先看报错再动手，比反复重装省事。
一、先把报错原文对上号
后台「外观 → 主题 → 添加新主题 → 上传主题」失败时，页面顶部会给一行提示。对照下面这张表，能省掉大半试错。
| 报错原文 | 原因 | 处理方向 |
|---|---|---|
| The uploaded file exceeds the upload_max_filesize directive in php.ini. | 主题包超过 PHP 单文件上传上限，默认常见 2M | 改 php.ini 与 nginx 两处体积限制 |
| The package could not be installed. The theme is missing the style.css stylesheet. | zip 内层多套了一层目录，或根本不是主题包 | 重新压缩，确保根目录下直接是 style.css |
| 无法创建目录。/ Could not create directory. | wp-content/themes 或 upgrade 目录不可写 | 改属主与 755 权限 |
| Fatal error: Allowed memory size of 134217728 bytes exhausted | 解压或启用时内存峰值超过上限 | 抬 memory_limit，关掉 demo 导入 |
| Unable to connect to the filesystem. Please confirm your credentials. | 文件属主与 PHP 运行用户不一致，WordPress 判定不能直写 | 统一属主，或声明 FS_METHOD 为 direct |
| No working transports found | PHP 缺 ftp 或 openssl 扩展 | 装扩展，或改用 direct 方式 |
二、上传体积超限：三处限制，改一处没用
WordPress 后台显示的上限，取三个值里最小的那个：PHP 的 upload_max_filesize、PHP 的 post_max_size、nginx 的 client_max_body_size。只改 php.ini 会发现上限数字变了，但传大包依旧中断，因为请求在进 PHP 之前就被 nginx 挡了，返回 413。
PHP 侧改这几行，位置在 php.ini：
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
max_input_time = 300
memory_limit = 256Mnginx 侧在 server 段或 http 段加一行：
client_max_body_size 64m;
fastcgi_read_timeout 300s;宝塔面板的位置分两处：PHP 配置在「软件商店 → PHP-8.1 → 设置 → 配置修改」，改完点保存并重启 PHP-FPM；nginx 的在「网站 → 站点 → 设置 → 配置文件」，找 client_max_body_size，没有就手动加在 server 块里。宝塔新版也可以在「网站 → 设置 → 网站目录」附近看到上传限制的提示，但真正生效的还是这两处。
改完怎么验证：进「工具 → 站点健康 → 信息 → 服务器」，看「上传文件大小上限」是不是 64M。数字没变说明改的配置文件不是当前 PHP 在用的那份，用 php --ini 或者一个 phpinfo 页面确认路径。
还有一种表现是进度条走到 100% 然后 502。这不是体积问题，是 fastcgi 超时或内存爆了，加 fastcgi_read_timeout 300s 并把 memory_limit 抬到 256M 以上再看。
装得很慢、一直转圈
还有一类卡顿更常见：在「添加新主题」里直接搜索安装，走的是 wordpress.org 的官方源，国内访问经常几十秒没响应，最后报「下载失败：cURL error 28」。这不是主题的问题，也不建议为此去改 hosts。
可行做法是把主题包下载到本地，用「上传主题」装。文件大就用 SFTP 直接传到 wp-content/themes/ 再解压，解压后确认目录层级正确，后台主题列表会立刻出现。这条路不经过 PHP 上传流程，绕开了体积和超时两个限制，是装大主题最稳的方式。
另外顺手看一眼 wp-content/upgrade 目录，升级中断会在这里留下临时文件夹，攒多了占空间，也可能让下一次安装报目录已存在。清空前确认站点没有正在进行的更新。
三、目录权限与属主
报「无法创建目录」时，先确认 wp-content 下三个目录的属主。WordPress 需要写的是 themes、plugins、upgrade、uploads 四个位置。SSH 下执行：
cd /www/wwwroot/example.com/wp-content
chown -R www:www themes plugins upgrade uploads
find themes -type d -exec chmod 755 {} ;
find themes -type f -exec chmod 644 {} ;属主名按环境改，CentOS 系常见 www，Debian 系常见 www-data。目录 755、文件 644 就够，不要图省事给 777。777 在部分主机的 suPHP / suEXEC 下反而会被拒绝执行，报 500。
宝塔用户更简单：「文件 → 选中 wp-content → 权限 → 所有者选 www、权限 755 → 应用到子目录」。改完再回后台上传一次，不用重启。
让你填 FTP 账号是怎么回事
上传页出现「要执行请求的操作，WordPress 需要访问您网页服务器的权限」，让你填主机名、FTP 用户名和密码。原因是 WordPress 检测到 PHP 进程对 wp-content 没有直接写权限——通常发生在用 root 通过 SSH 上传过文件、或从别的服务器打包迁移过来之后，文件属主变成了 root。
正规做法是把属主改回 www。改不了（比如虚拟主机不给 SSH）时，在 wp-config.php 里声明直写：
define( 'FS_METHOD', 'direct' );加完还提示，说明 PHP 确实没有写权限，这条路走不通，只能联系主机商。不要在这里填自己的 FTP 账号反复试，密码错三次有些主机会封 IP。
如果提示的是 No working transports found，跟权限无关，是 PHP 没编译 ftp 扩展也没开 openssl。宝塔在「软件商店 → PHP → 设置 → 安装扩展」里装 fileinfo 和 ftp 即可；装不了就用 direct 方式绕开。
四、包结构不对：缺 style.css
从主题站下载的包，常见两种结构问题。第一种是双层目录：解压后是 theme-name/theme-name/style.css，WordPress 只认第一层，找不到 style.css 就报缺少样式表。第二种是整站包：里面带着 wp-content、wp-includes、数据库 sql，那是整站备份，不是主题。
正确的结构只有一种：
theme-name/
├── style.css
├── functions.php
├── index.php
├── screenshot.png
└── assets/手工处理步骤：本地解压，进到最内层确认 style.css 和 functions.php 在同一级，把这一层重新压成 zip（压缩时选中文件夹本身，不要在文件夹里全选再压），上传。macOS 压缩会额外生成 __MACOSX 目录，删掉再传，否则可能出现「样式表缺失」的误报。
还有一种情况是主题包本身不完整，style.css 头部缺 Theme Name 或 Theme URI。这种包即使结构对，启用后也会在主题列表里显示为「已损坏的主题」，只能找作者要完整包。
五、内存不足导致中断
大主题带 demo 导入、自带页面构建器时，解压和启用的瞬间内存峰值可能到 300M 以上。报错原文里会带文件路径，常见是 wp-admin/includes/class-wp-upgrader.php 或 class-theme-upgrader.php，出现这个路径就说明是升级流程本身被打断，不是主题代码有问题。
三处一起抬：php.ini 的 memory_limit = 256M；wp-config.php 里加 define('WP_MEMORY_LIMIT', '256M'); 和 define('WP_MAX_MEMORY_LIMIT', '512M');；面板里给 PHP 进程的内存限制。三层的关系和优先级在 内存超限 里拆过，这里只强调：wp-config 里的值不能突破 php.ini 的硬上限，主机禁用了 ini_set 时写了也不生效。
临时办法是先停掉占用高的插件再装主题，装完再开回来。长期办法是换一个不带重型 demo 导入的主题，很多「装不上」其实是主题体积和主机配置不匹配，不是故障。
六、装完启用报错的收尾检查
- PHP 版本是否满足主题要求。后台「外观 → 主题 → 主题详情」里有 Requires PHP，低于要求会直接白屏。
- 必装插件是否齐全。很多主题把核心功能放在配套插件里，只装主题会出现首页模块空白，这类依赖关系在 主题推荐 里有说明。
- 是否和现有插件抢同名函数。启用瞬间报
Cannot redeclare，就是函数重名，处理思路见 插件冲突。 - 子主题是否需要重建。换主题后旧子主题的模板会失效，定制部分要迁过去，做法见 主题定制。
- 固定链接重新保存一次。部分主题注册了新的 rewrite 规则，不刷新会 404。
另外，主题启用时会往数据库写一批设置：菜单位置、小工具归属、主题选项、首页显示方式。装之前做一次数据库备份，出问题直接回滚，比重新配一遍菜单快得多，回滚比重装一遍干净。
装主题这件事，八成失败都出在「包不对」和「权限不对」这两个朴素原因上，剩下两成是主机配置太低。环境本身需要重搭的，可以看 安装部署 那一篇。手上有个包反复装不上，把报错截图和 zip 的目录结构发到 web@wordpressx.com，或者打 13280692153，我们这边看一眼就知道卡在哪。