Flarum 1.x 升级至 2.0.0-rc.3 完整记录

前言

2026 年 6 月 11 日，我们将「爱开发社区」（https://forum.idev.top）从 Flarum 1.8.x 升级到了 Flarum 2.0.0-rc.3。本文记录了整个升级过程、遇到的问题及解决方案，供同好参考。

环境信息

项目	版本
PHP	8.5.7
MySQL	8.0.34
Composer	2.x
Web 服务器	Angie（Nginx 兼容）
升级前 Flarum	v1.8.10
升级后 Flarum	v2.0.0-rc.3

升级步骤

第一步：检查 PHP 版本

Flarum 2.0 要求 PHP 8.3 或更高版本。

php --version

确认当前 PHP 版本满足要求后继续。

第二步：备份数据库

升级前务必备份数据库：

mysqldump -u root -p flarum > flarum_backup_$(date +%Y%m%d).sql

第三步：修改 composer.json

按照 Flarum 官方升级文档，需要做以下修改：

将 flarum/core 改为 ^2.0
将所有扩展（包括官方扩展如 flarum/tags、flarum/mentions 等）的版本约束改为 *
添加 "minimum-stability": "beta"（RC 阶段必需）
添加 "prefer-stable": true

{
    "minimum-stability": "beta",
    "prefer-stable": true,
    "require": {
        "flarum/core": "^2.0",
        "flarum/approval": "*",
        "flarum/tags": "*",
        ...
    }
}

第四步：移除不兼容扩展

这是升级过程中最耗时的一步。通过逐一运行 composer update，根据报错信息识别并移除不兼容 Flarum 2.0 的扩展。

我们采用的策略是：先用 Packagist API 批量检查每个扩展是否有支持 flarum/core ^2.0 的版本，然后只保留兼容的扩展。

最终移除了 27 个不兼容扩展：

核心功能类：askvortsov/flarum-markdown-tables、ffans/clipboardjs、dem13n/discussion-cards、michaelbelgium/flarum-discussion-views
OAuth 登录：blt950/oauth-generic、import-ai/flarum-oauth-passport
搜索相关：clarkwinkelmann/flarum-ext-advanced-search-highlight、ganuonglachanh/flarum-ext-search、ganuonglachanh/sonic
UI/样式类：datlechin/flarum-scroll-buttons、fof/cookie-consent、fof/nightmode、ramon/colored
内容管理：clarkwinkelmann/flarum-ext-discussion-bookmarks、rehiy/flarum-reply-to-see、matteociaroni/flarum-old-content
其他：davwheat/flarum-ext-ads、malago/flarum-ads、foskym/flarum-activity-graph、gitzaai/flarum-ext-hljs2、gtdxyz/flarum-ext-discussion-paginator、idevsig/flarum-asciinema、lrysia/pagination、nearata/flarum-ext-tags-color-generator、the-turk/flarum-stickiest、fof/pretty-mail、flarum-lang/chinese-simplified

完整列表见 removed-extensions.md。

第五步：运行 composer update

composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies

这一步会：

升级 flarum/core 到 2.0.0-rc.3
升级所有官方扩展到 2.x 版本
升级 fof 系列扩展到 2.x beta 版本
升级底层依赖（Laravel Illuminate、Symfony、Doctrine 等）

第六步：运行数据库迁移

php flarum migrate

本次升级涉及 14 个新 migration，包括：

create_unsubscribe_tokens_table
convert_preferences_to_json_in_users
convert_data_to_json_in_notifications
change_to_theme_mode_setting_and_preference
create_queue_jobs / create_queue_failed_jobs
add_position_to_groups_table
以及 fof-pages、flarum-tags、fof-upload 等扩展的迁移

第七步：清除缓存

php flarum cache:clear

第八步：重启 PHP-FPM

systemctl reload php-fpm

第九步：修复文件权限

升级后首次访问时遇到 500 错误，排查发现 public/assets/js 目录的所有者在升级过程中变为 root:root，导致 Web 服务器（以 www 用户运行）无法在其中创建编译后的 JS 子目录。

chown -R www:www /data/wwwroot/forum.idev.top/public/assets/js

第十步：验证

# 检查版本
php flarum info

# 检查网站是否可访问
curl -sS -o /dev/null -w "%{http_code}" https://forum.idev.top
# 应返回 200

遇到的问题

1. fof/pages 的 dev-master 分支已不存在

原始 composer.json 中 fof/pages 指定了 dev-master，但该分支已从 Packagist 移除。需要改为 * 以让 Composer 自动解析最新兼容版本。

2. fof/pretty-mail 存在安全公告

Packagist 报告了安全公告 PKSA-zqkh-gtty-c5yv，阻止了该包的安装。在 composer.json 中添加了忽略配置：

"policy": {
    "advisories": {
        "ignore": ["PKSA-zqkh-gtty-c5yv"]
    }
}

3. lrysia/pagination 残留文件

虽然 composer update 移除了该扩展，但其编译后的缓存文件仍被 PHP-FPM 加载，导致 Trait "Flarum\Query\ApplyQueryParametersTrait" not found 错误。通过清除缓存并重启 PHP-FPM 解决。

4. extend.php 中的自定义代码

原始 extend.php 包含为 idevsig/flarum-asciinema 编写的自定义 BBCode 配置。由于该扩展已被移除，需要清理相关代码，避免潜在冲突。

升级后状态

升级完成后，以下扩展已成功升级到 Flarum 2.0 兼容版本：

扩展	版本
flarum/core	v2.0.0-rc.3
flarum/tags	v2.0.0-rc.3
flarum/mentions	v2.0.0-rc.3
fof/pages	2.0.0-beta.2
fof/upload	2.0.0-beta.5
fof/gamification	2.0.0-beta.4
fof/best-answer	2.0.0-beta.5
v17development/flarum-seo	4.0.0-beta.2
walsgit/recycle-bin	2.0.4
darkle/fancybox	3.0.0-beta.1

共 184 个包升级，25 个新包安装，48 个包移除。

注意事项

PHP 版本：Flarum 2.0 要求 PHP 8.3+，如果当前版本低于 8.3，需要先升级 PHP。
MariaDB 用户：如果使用 MariaDB，需要在 config.php 中将 driver 从 mysql 改为 mariadb。
minimum-stability：当前是 RC 阶段，必须设置 "minimum-stability": "beta"。正式发布后应改回 "stable"。
扩展兼容性：升级前务必检查所有第三方扩展是否有 Flarum 2.0 兼容版本。可以在 Packagist 或扩展的 Discuss 讨论帖中查看。
文件权限：升级后检查 public/assets 目录权限，确保 Web 服务器用户有写入权限。
本地 Extenders：如果使用了本地 Extender（如 extend.php 中的自定义代码），需要检查其与 Flarum 2.0 API 的兼容性。