进阶 docs.flarum.org 2026-10-15 14:50:53 · 19 阅读
第19章 Flarum 2.0 升级指南
Version: 2.x
第19章：升级到 Flarum 2.0
警告：在升级生产论坛之前，请先备份数据库和文件，并在预发布环境（staging copy）上测试升级流程。
本指南将指导你从 Flarum v1 升级到 v2。你需要安装 Composer——如果不熟悉，请先阅读我们的指南。
使用 Composer 而非扩展管理器执行此升级。扩展管理器无法将论坛从 1.x 升级到 2.0。它的更新检查会跳过 flarum/core，因此永远看不到存在新的主版本，并会拒绝升级；且旨在预先放宽扩展版本约束的步骤实际上并未放宽它们。请使用命令行执行此升级。一旦升级到 2.0 之后，扩展管理器仍是常规更新的最佳工具，因为那些更新都保持在同一主版本内。它无法处理的只是跨主版本的升级。
开始前准备
在进行任何更改之前，请完成以下检查清单：
1. 先更新 v1 安装
确保当前的 Flarum 1.x 安装及所有扩展都处于最新的 1.x 版本。这能缩小你要跨越的版本差距，更便于排查问题。如果尚未处于最新的 v1 版本，请运行：
composer update --prefer-dist --no-plugins --no-dev -a --with-dependencies
php flarum migrate
php flarum cache:clear
Composer 可能会拒绝执行此命令。Flarum 1.x 依赖 league/flysystem 1.x，该版本存在安全公告且没有修复过的 1.x 版本，因此当前版本的 Composer 会阻止它，导致更新在开始前就失败： flarum/core[...] require league/flysystem ^1.0.11 -> found league/flysystem[1.0.11, ..., 1.1.10]
but these were not loaded, because they are affected by security advisories
对于 Flarum 1.8，忽略该安全公告是推荐做法。请将以下内容添加到你的 composer.json 中，然后重新运行命令： "config": {
"audit": {
"ignore": {
"GHSA-cxf4-7mrp-vvpr": "league/flysystem 1.x (required by flarum/core 1.x) has no patched release"
}
}
}
1. 配置文件 此配置仅适用于 1.x 版本线。Flarum 2.0 采用 Flysystem 3.x，无需该配置项，因此升级后即可移除。 2. 检查 PHP 版本 Flarum 2.0 要求 PHP 8.3 或更高版本。请使用 `php --version` 查看当前版本。如果低于 8.3，请先升级 PHP 再继续操作。 同时，请确认使用的是 Composer 2：运行 `composer --version`。 3. 检查不兼容或已被取代的扩展 部分扩展已不兼容 v2 版本，另一些则已被替代： * 移除 `blomstra/database-queue` 和 `blomstra/fontawesome`——这些功能现已内置于 `flarum/core` 中。 * 用 `fof/redis` 替换 `blomstra/flarum-redis`，用 `fof/horizon` 替换 `blomstra/horizon`。 * 用 `flarum/extension-manager` 替换 `flarum/package-manager`。该包在 v2 中已更名，旧名称仍可解析，但 Composer 每次运行都会警告该包已废弃。 对于其他所有扩展，请检查其 Discuss 线程或 Packagist 页面，确认是否有支持 v2 的版本。如果没有，您必须移除它们。请耐心等待扩展开发者更新。 4. 更新 composer.json 将所有扩展（包括内置扩展如 `flarum/tags`、`flarum/mentions`、`flarum/likes` 等）的版本字符串设置为 `*`。然后将 `flarum/core` 设置为 `^2.0`： `"flarum/core": "^2.0", "flarum/tags": "*", "flarum/mentions": "*"` 接着，在 `composer.json` 的顶层（而非 `require` 内部），允许 beta 版本发布但优先选择稳定版： `"minimum-stability": "beta", "prefer-stable": true` Flarum 2.0 本身已经稳定，但很多扩展目前只发布了适配 2.0 的 beta 版本。如果把 minimum-stability 设为 stable，Composer 就装不上这些扩展，升级也会失败。而 prefer-stable 能让其他依赖都保持稳定版：只有当某个包确实没有匹配的稳定版本时，Composer 才会选用 beta 版。等扩展陆续发布稳定版后，你下次更新时 Composer 会自动切换过去。等你的所有扩展都有了稳定版，就可以把 minimum-stability 改回 stable。 5. 如果使用 MariaDB，请更新 config.php Flarum 2.0 区分 MySQL 和 MariaDB。如果你的论坛跑在 MariaDB 上，必须把 config.php 中的 driver 值改成 mariadb。升级到 2.0 后如果仍保留 mysql，会报兼容性错误。 不确定自己用的是哪个？在 Flarum 1.x 中，php flarum info 不管实际跑的是什么服务器，那一行都标着 MySQL version，所以要看版本字符串而不是标签：MySQL version: 11.8.9-MariaDB-ubu2404
这个论坛实际用的是 MariaDB，虽然标签写的是 MySQL，但也需要做这个修改。升级后，2.0 会正确显示为 MariaDB version。 'debug' => true,
'offline' => false,
'database' =>
array (
'driver' => 'mysql',
'driver' => 'mariadb',
'host' => 'localhost',
'port' => 3306,
6. 检查本地的 extenders 如果你的站点用了本地 extender，升级前先检查它们是否兼容 Flarum 2.0 的 API 变更。 7. 禁用第三方扩展 建议在运行升级前先在管理后台禁用第三方扩展。这不是硬性要求，但万一出问题会更方便排查。升级完成、论坛能正常访问后，再把它们逐个启用。 运行升级 完成上面的检查清单后，执行： composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear
然后重启 PHP 进程，如有 opcache 也一并重启。 故障排查 扩展管理器提示没有可用的新主版本 这是正常现象：如本页开头所述，扩展管理器无法完成 1.x 到 2.0 的升级，请按上面的方法用 Composer 执行升级。 update 命令没有升级 Flarum 如果输出中有： Nothing to modify in lock file
php flarum migrate
php flarum cache:clear
Composer 可能会拒绝执行此命令。Flarum 1.x 依赖 league/flysystem 1.x，该版本存在安全公告且没有修复过的 1.x 版本，因此当前版本的 Composer 会阻止它，导致更新在开始前就失败： flarum/core[...] require league/flysystem ^1.0.11 -> found league/flysystem[1.0.11, ..., 1.1.10]
but these were not loaded, because they are affected by security advisories
对于 Flarum 1.8，忽略该安全公告是推荐做法。请将以下内容添加到你的 composer.json 中，然后重新运行命令： "config": {
"audit": {
"ignore": {
"GHSA-cxf4-7mrp-vvpr": "league/flysystem 1.x (required by flarum/core 1.x) has no patched release"
}
}
}
1. 配置文件 此配置仅适用于 1.x 版本线。Flarum 2.0 采用 Flysystem 3.x，无需该配置项，因此升级后即可移除。 2. 检查 PHP 版本 Flarum 2.0 要求 PHP 8.3 或更高版本。请使用 `php --version` 查看当前版本。如果低于 8.3，请先升级 PHP 再继续操作。 同时，请确认使用的是 Composer 2：运行 `composer --version`。 3. 检查不兼容或已被取代的扩展 部分扩展已不兼容 v2 版本，另一些则已被替代： * 移除 `blomstra/database-queue` 和 `blomstra/fontawesome`——这些功能现已内置于 `flarum/core` 中。 * 用 `fof/redis` 替换 `blomstra/flarum-redis`，用 `fof/horizon` 替换 `blomstra/horizon`。 * 用 `flarum/extension-manager` 替换 `flarum/package-manager`。该包在 v2 中已更名，旧名称仍可解析，但 Composer 每次运行都会警告该包已废弃。 对于其他所有扩展，请检查其 Discuss 线程或 Packagist 页面，确认是否有支持 v2 的版本。如果没有，您必须移除它们。请耐心等待扩展开发者更新。 4. 更新 composer.json 将所有扩展（包括内置扩展如 `flarum/tags`、`flarum/mentions`、`flarum/likes` 等）的版本字符串设置为 `*`。然后将 `flarum/core` 设置为 `^2.0`： `"flarum/core": "^2.0", "flarum/tags": "*", "flarum/mentions": "*"` 接着，在 `composer.json` 的顶层（而非 `require` 内部），允许 beta 版本发布但优先选择稳定版： `"minimum-stability": "beta", "prefer-stable": true` Flarum 2.0 本身已经稳定，但很多扩展目前只发布了适配 2.0 的 beta 版本。如果把 minimum-stability 设为 stable，Composer 就装不上这些扩展，升级也会失败。而 prefer-stable 能让其他依赖都保持稳定版：只有当某个包确实没有匹配的稳定版本时，Composer 才会选用 beta 版。等扩展陆续发布稳定版后，你下次更新时 Composer 会自动切换过去。等你的所有扩展都有了稳定版，就可以把 minimum-stability 改回 stable。 5. 如果使用 MariaDB，请更新 config.php Flarum 2.0 区分 MySQL 和 MariaDB。如果你的论坛跑在 MariaDB 上，必须把 config.php 中的 driver 值改成 mariadb。升级到 2.0 后如果仍保留 mysql，会报兼容性错误。 不确定自己用的是哪个？在 Flarum 1.x 中，php flarum info 不管实际跑的是什么服务器，那一行都标着 MySQL version，所以要看版本字符串而不是标签：MySQL version: 11.8.9-MariaDB-ubu2404
这个论坛实际用的是 MariaDB，虽然标签写的是 MySQL，但也需要做这个修改。升级后，2.0 会正确显示为 MariaDB version。 'debug' => true,
'offline' => false,
'database' =>
array (
'driver' => 'mysql',
'driver' => 'mariadb',
'host' => 'localhost',
'port' => 3306,
6. 检查本地的 extenders 如果你的站点用了本地 extender，升级前先检查它们是否兼容 Flarum 2.0 的 API 变更。 7. 禁用第三方扩展 建议在运行升级前先在管理后台禁用第三方扩展。这不是硬性要求，但万一出问题会更方便排查。升级完成、论坛能正常访问后，再把它们逐个启用。 运行升级 完成上面的检查清单后，执行： composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear
然后重启 PHP 进程，如有 opcache 也一并重启。 故障排查 扩展管理器提示没有可用的新主版本 这是正常现象：如本页开头所述，扩展管理器无法完成 1.x 到 2.0 的升级，请按上面的方法用 Composer 执行升级。 update 命令没有升级 Flarum 如果输出中有： Nothing to modify in lock file
或者 flarum/core 未出现在已更新包列表中：
请确保 composer.json 中所有第三方扩展的版本字符串都设为 *。
请确保 flarum/core 设置为 ^2.0，而非 v1.8 这类具体版本。
Composer 报告依赖冲突
运行 composer why-not flarum/core 2.0.0 来找出阻碍升级的因素。输出大致如下（版本号仅为示例）：
flarum/flarum - requires flarum/core (^1.0)
fof/moderator-notes 0.4.4 requires flarum/core (^1.0)
some/extension 1.2.3 requires flarum/core (^1.0)
这意味着其中一个或多个扩展尚无兼容 v2 的版本可供 Composer 安装。如果该扩展已标记 2.0 beta，请检查 minimum-stability 是否为 beta 且 prefer-stable 是否为 true（步骤 4）。如果该扩展根本没有 2.0 版本，请移除它再重试。
请确保运行 composer update 时使用了上述所有参数标志。
若仍无法解决，请在我们的支持论坛发帖求助，并附上 php flarum info 和 composer why-not flarum/core 2.0.0 的输出结果。
更新后出现错误
如果升级后论坛无法访问（如出现空白页、500 错误等），请按照我们的故障排查指南操作。
