# 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。整个过程可以说是踩了不少坑，所以干脆趁着印象还在，把这套完整的折腾记录写下来，希望能给打算升级的朋友做个参考。

<!--more-->

## 环境信息

| 项目 | 版本 |
|------|------|
| 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 或更高版本。

```bash
php --version
```

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

### 第二步：备份数据库

升级前务必备份数据库：

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

### 第三步：修改 composer.json

按照 [Flarum 官方升级文档](https://docs.flarum.org/2.x/update)，需要做以下修改：

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

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

### 第四步：移除不兼容扩展

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

我们采用的策略是：先用 [Packagist API](https://packagist.org/) 批量检查每个扩展是否有支持 `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](removed-extensions.md)。

### 第五步：运行 composer update

```bash
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 等）

### 第六步：运行数据库迁移

```bash
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 等扩展的迁移

### 第七步：清除缓存

```bash
php flarum cache:clear
```

### 第八步：重启 PHP-FPM

```bash
systemctl reload php-fpm
```

### 第九步：修复文件权限

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

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

### 第十步：验证

```bash
# 检查版本
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` 中添加了忽略配置：

```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 个包移除。

## 升级前必看（少走弯路）

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](https://packagist.org/) 或扩展的 [Discuss 讨论帖](https://discuss.flarum.org/t/extensions) 中查看。
5. **文件权限**：升级后检查 `public/assets` 目录权限，确保 Web 服务器用户有写入权限。
6. **本地 Extenders**：如果使用了本地 Extender（如 `extend.php` 中的自定义代码），需要检查其与 Flarum 2.0 API 的兼容性。

## 参考链接

- [Flarum 2.0 升级文档](https://docs.flarum.org/2.x/update)
- [Flarum 2.0.0-rc.3 发布说明](https://discuss.flarum.org/d/39406-flarum-200-rc3-released-built-by-the-community-almost-ready-for-everyone)
- [Packagist 扩展搜索](https://packagist.org/)