Tutorial|教程 XenForo 插件安装完整教程（三种方式详解）

[oksgo]

📦 XenForo 插件安装完整教程（三种方式详解）​

适用版本：XenForo 2.2 / 2.3 | 更新：2026-04-26

---

📋 前置说明​

XenForo 的插件（Add-on）有以下几种常见安装方式：

1. 后台上传 ZIP 安装（最简单，推荐新手）
2. FTP/宝塔 手动上传安装（ZIP 过大或后台上传失败时使用）
3. CLI 命令行安装（推荐开发者 / 大型插件）

---

✅ 方式一：后台直接上传 ZIP（推荐）​

第一步：下载插件包​

从插件作者或交易帖获取插件压缩包，文件名通常为：

• PluginName-x.x.x.zip — 直接上传包（内含 _output 文件夹结构）
• upload.zip 或 files.zip — 需要先手动上传文件，再后台安装 XML

⚠️ 注意区分：不是所有 zip 都能直接在后台上传，先看插件说明文档。

第二步：进入后台插件管理​

登录后台 → 左侧菜单 → Add-ons（插件）→ 点击右上角 Install from Archive（从压缩包安装）

第三步：上传并安装​

1. 点击 Choose File，选择插件的 .zip 文件
2. 点击 Upload & Install
3. 等待安装完成，页面会显示插件信息确认界面
4. 点击 Install Add-on 确认安装

看到 "Add-on installed successfully" 即安装成功 🎉

---

🗂️ 方式二：FTP / 宝塔手动上传安装​

适用场景：插件包含大量文件，或后台上传提示"文件过大"。

第一步：解压插件包​

将下载的 zip 解压到本地，通常会有以下结构：

插件解压后/
├── upload/               ← 这个文件夹内的内容需要上传到服务器
│   ├── src/
│   │   └── addons/
│   │       └── VendorName/
│   │           └── AddonName/
│   ├── js/
│   └── styles/
└── README.md

第二步：上传文件到服务器​

宝塔面板操作：

1. 宝塔 → 文件 → 进入网站根目录（如 /www/wwwroot/你的域名/）
2. 将插件 upload/ 文件夹内的所有内容上传到网站根目录
3. 确认文件合并正确（如 src/addons/VendorName/AddonName/ 目录存在）

FTP（FileZilla / WinSCP）操作：

1. 连接服务器，进入网站根目录
2. 将本地 upload/ 目录内的文件拖拽到服务器根目录
3. 选择"合并"（不要替换整个目录）

第三步：后台完成安装​

登录后台 → Add-ons → 点击右上角 Install from File System（从文件系统安装）

1. 在列表中找到刚刚上传的插件（显示为"Found on file system, not installed"状态）
2. 点击插件右侧的 Install
3. 确认插件信息，点击 Install Add-on

---

⌨️ 方式三：CLI 命令行安装（推荐进阶用户）​

前提​

需要 SSH 连接服务器权限（宝塔面板用户可使用宝塔的"终端"功能）。

操作步骤​

1. 先按照方式二，将插件文件上传到服务器对应目录
2. SSH 连接服务器，进入网站根目录：

cd /www/wwwroot/你的域名

• 执行安装命令：

# 安装指定插件（替换 VendorName/AddonName 为实际的插件 ID）
php cmd.php xf-addon:install VendorName/AddonName

# 如果插件目录已存在，可以使用升级命令
php cmd.php xf-addon:upgrade VendorName/AddonName

# 查看当前所有已安装插件
php cmd.php xf-addon:list

进入 src/addons/VendorName/AddonName/addon.json 文件，其中 "addon_id" 字段就是插件 ID，格式为 VendorName/AddonName

---

🔄 如何升级插件​

方式 A：后台上传升级包​

后台 → Add-ons → 找到对应插件 → 点击 Upload New Version → 上传新版 zip → 确认安装

方式 B：覆盖文件后后台升级​

1. 将新版文件覆盖上传到服务器（同安装步骤）
2. 后台 → Add-ons → 找到插件 → 点击 Upgrade（如果有版本更新会显示此按钮）

方式 C：CLI 升级​

php cmd.php xf-addon:upgrade VendorName/AddonName

---

🗑️ 如何卸载插件​

后台 → Add-ons → 找到对应插件 → 点击 Uninstall → 确认卸载

⚠️ 卸载会删除插件的数据库表和数据，卸载前建议备份数据库。

卸载完成后，如果不再使用，可手动删除服务器上的插件文件夹：
src/addons/VendorName/AddonName/

---

⚡ 安装后必做事项​

1. 清除缓存：后台 → Tools → Rebuild Caches → 点击 Rebuild
2. 重建模板（如插件修改了模板）：
   

   php cmd.php xf:template-rebuild

3. 检查插件配置：部分插件安装后需要在后台 → Options 中进行额外配置
4. 检查权限：后台 → User Groups → 确认各用户组对新插件功能的权限设置

---

❓ 常见安装问题​

隐藏: 上传 ZIP 提示"文件过大"怎么办？

调整 PHP 上传大小限制：
宝塔面板：
宝塔 → 软件商店 → PHP → 设置 → 配置修改 → 修改以下参数：

upload_max_filesize = 100M
post_max_size = 100M

保存后重启 PHP-FPM。
或改用方式二（手动上传文件）。

隐藏: 安装时提示"Class not found"或"Autoloader error"？

说明插件文件没有上传完整，或上传到了错误的目录。

1. 确认 src/addons/VendorName/AddonName/ 目录存在且文件完整
2. 检查文件权限：宝塔 → 文件 → 右键目录 → 权限 755
3. 执行缓存重建：

php cmd.php xf:rebuild-master-data

隐藏: 插件安装后页面报 500 错误？

1. 查看 XenForo 错误日志：后台 → Logs → Server Error Log
2. 查看 PHP 错误日志（宝塔 → 网站 → 错误日志）
3. 临时开启调试模式（仅用于排查，排查后必须关闭）：

// 在 src/config.php 追加
$config['debug'] = true;

确认错误原因后，将 debug 改回 false。

隐藏: 插件安装后没有出现在后台菜单？

• 部分插件通过 Options 而非独立菜单项配置，检查后台 → Setup → Options
• 尝试清除缓存：后台 → Tools → Rebuild Caches
• 确认插件已启用：后台 → Add-ons → 确认插件状态为 Enabled（绿色）

隐藏: 如何临时禁用插件（不卸载）？

后台 → Add-ons → 找到插件 → 点击 Disable

禁用不会删除数据，随时可以重新 Enable。

如果后台无法访问（报错循环）：
在 src/config.php 追加以下代码可强制禁用所有插件：

$config['enableListeners'] = false;

进入后台排查后记得删除此行。

---

如有安装问题欢迎回帖，附上错误截图或日志内容更容易得到帮助。

 

讨论|help  如何正确翻译语言包

Tutorial|教程  制作XENFORO插件

[fishcpy]

为什么我这里显示
仅当您具有ZipArchive支持时，才支持从存档进行安装。 您可能需要让您的主机启用此功能。

 

[oksgo]

也可以FTP上传安装