插件安装失败主因是系统源失效、权限配置错误、SELinux拦截、镜像源不可达或编译环境缺失；需依次检查并修复yum/apt源、/www目录权限与挂载参数、SELinux策略、CA证书及gcc-c++等开发工具。
插件安装卡在“正在下载”或报 Connection refused
这是国内云服务器最常遇到的镜像源失效问题——宝塔默认走官方源，但 CentOS 8+、Rocky/AlmaLinux 的 appstream 和 baseos 仓库早已下线，mirrors.centos.org 解析失败或返回 404，导致依赖根本拉不下来。
- 先确认是否真卡网络：执行
curl -I https://mirrors.aliyun.com，若返回HTTP/2 200说明本地网络通，问题出在系统源配置；若超时或报Could not resolve host，则要优先修 DNS 或换镜像脚本安装 - 别急着重装宝塔——90% 的插件安装失败，根源是系统级
yum或apt本身已瘫痪，面板只是暴露了底层问题 - CentOS 7 用户直接换阿里云源：
mv /etc/yum.repos.d/CentOS-Base.repo /etc/yum.repos.d/CentOS-Base.repo.bak && curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-vault-7.9.2009.repo，再跑yum clean all && yum makecache - CentOS 8 Stream / Rocky 8 / AlmaLinux 8 用户必须切到
mirrorlist替代方案，不能硬套 CentOS 7 的 repo 文件；推荐用宝塔官方适配脚本：curl -sSO https://download.bt.cn/install/install_6.0.sh && bash install_6.0.sh（该脚本已内置 Stream 兼容逻辑）
插件提示 Permission denied 或写入 /www 失败
不是权限没给 root，而是宝塔运行用户（通常是 www）对目标目录无写入权，尤其常见于手动挂载磁盘后未调整属主，或使用了 LVM/快照卷但 /www 挂载点权限被重置。
- 检查
/www所在分区挂载参数：执行mount | grep "/www"，若输出含noexec、nosuid或ro，需修改/etc/fstab去掉这些限制并mount -o remount /www - 确认属主归属：
ls -ld /www应显示root:root或root:www，且权限为drwxr-xr-x；若属主是普通用户或权限为700，运行chown -R root:www /www && chmod -R 755 /www - SELinux 启用状态下，即使权限正确也会拦截——临时验证：执行
setenforce 0，再试装插件；若成功，说明 SELinux 策略冲突，需执行semanage fcontext -a -t httpd_sys_rw_content_t "/www(/.*)?" && restorecon -Rv /www
Ubuntu/Debian 上插件安装报 E: Failed to fetch 或源地址 404
Ubuntu 默认源 archive.ubuntu.com 在国内延迟高、偶发不可达；Debian 12（bookworm）部分镜像站尚未同步完所有组件，容易在安装 PHP 插件时缺 libapache2-mod-php 这类包。
- Ubuntu 22.04 推荐清华源：
sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g; s/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list，然后apt update - Debian 12 必须用中科大源，且注意安全源路径变化：删掉原
sources.list全部内容，写入两行：deb https://mirrors.ustc.edu.cn/debian bookworm main non-free non-free-firmware contrib和deb https://mirrors.ustc.edu.cn/debian-security bookworm-security main - 别漏掉
apt install ca-certificates——某些镜像站 HTTPS 证书校验失败会导致整个 apt update 中断，插件安装自然失败
安装日志里出现 error: C++ preprocessor "/lib/cpp" fails sanity check
这不是插件本身的问题，是 PHP 编译环境缺失——宝塔在后台编译安装 PHP（比如装 PHP 8.3 插件）时，发现连基础 C++ 预处理器都找不到，直接 abort。
- CentOS/Rocky/AlmaLinux：运行
yum groupinstall "Development Tools" -y && yum install gcc-c++ glibc-headers make cmake -y - Ubuntu/Debian：运行
apt install build-essential libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev -y - 注意：
gcc-c++和build-essential是关键，没它们，任何带编译步骤的插件（如 Pure-Ftpd、PHP 源码版）必跪 - 装完别跳过验证：执行
g++ --version和cpp /dev/null -o /dev/null，后者不报错才算真正就绪
真正麻烦的从来不是“点一下安装”，而是插件背后那层系统依赖链——它串起了镜像源、磁盘挂载、SELinux 策略、编译工具链。任何一个环节松动，都会在安装完成前最后一秒报错，而且错误信息往往指向表层，实际得往底下挖三层。
