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 版本

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

php --version

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

第二步：备份数据库

升级前务必备份数据库：

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

第三步：修改 composer.json

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

1. 将 flarum/core 改为 ^2.0
2. 将所有扩展（包括官方扩展如 flarum/tags、flarum/mentions 等）的版本约束改为 *
3. 添加 "minimum-stability": "beta"（RC 阶段必需）
4. 添加 "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 兼容版本：

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

升级前必看（少走弯路）

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

参考链接

• Flarum 2.0 升级文档
• Flarum 2.0.0-rc.3 发布说明
• Packagist 扩展搜索