安装NodeJS

下载并解压

wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz
tar xvJf node-v22.12.0-linux-x64.tar.xz
mv node-v22.12.0-linux-x64 /usr/local/node-v22.12.0

设置PATH

echo 'export PATH=$PATH:/usr/local/nodejs/bin' >> /etc/bash.bashrc && source /etc/bash.bashrc

创建脚本nano /usr/local/node-v22.12.0/link_nodejs.sh

用于设置该版本到path

#!/bin/bash

# 获取脚本所在的目录
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# 检查目标目录是否存在，如果不存在则创建
if [ ! -d "/usr/local/nodejs/" ]; then
    sudo mkdir -p "/usr/local/nodejs/"
fi

# 源目录和目标目录
SOURCE_DIR="$SCRIPT_DIR/bin"
TARGET_DIR="/usr/local/nodejs/bin"

# 清除原有的bin
if [ -d "$TARGET_DIR" ]; then
    rm "$TARGET_DIR"
fi

# 创建软链接
sudo ln -s "$SOURCE_DIR" "$TARGET_DIR"

运行脚本

cd /usr/local/node-v22.12.0
chmod +x link_nodejs.sh
./link_nodejs.sh

安装yarn

要管理包有许多更好的选择，，例如pnpm或者bun，用yarn单纯是因为CLI里面也用的yarn，这样能少安装一个包管理器（先是安装到了pnpm然后又退回来卸了）

npm install -g yarn

按照教程进行

要命的是我也不记得从哪里找到的步骤了，，不过问题不大

接下来的步骤都需要在www-data用户下进行（运行flarum的用户），不然包安装的地方www-data没权限使用（是的，又是一次踩坑）

sudo -u www-data -s

安装webpack 和 Flarum CLI 2.0

需要注意版本对应，比如工坊论坛目前是1.x，那么就需要安装2.0.0的CLI

对应关系在CLI的github链接里有

yarn global add webpack
yarn global add @flarum/cli@^2.0.0

运行flarum-cli试试

发现没法全局运行——

看到用户目录/var/www/下有个.yarn/bin所以添加到全局变量

echo 'export PATH=$PATH:/var/www/.yarn/bin' >> ~/.bashrc && source ~/.bashrc

OK了。前期准备完成。

创建插件

这里有教程

虽然用CLI能够很快创建模板，但是手动搭一遍有助于获得对扩展的整体认知，使用CLI也能更好

然后你就会发现CLI还是有很多看不懂的选项

我们首先需要一个开发的地方， cd 到 flarum 根目录运行以下命令

composer config repositories.0 path "packages/*"

它会在conposer.json的末尾添加这个东西

{
  // 其它内容...
    "repositories": [{
            "type": "path",
            "url": "packages/*"
        }]
}

这样 composer 就会在这个路径找拓展了

在 flarum 根目录创建 packages 文件夹并 cd 进去，运行 CLI 创建新项目

mkdir packages
cd packages
flarum-cli init test

（这里的名字test只决定文件夹的名字）

照着提示填填，看不懂的直接回车取默认值，虽然不知道为什么 git init 选 yes 会报错不过问题不大

我这里设置了 id 是 sch246/flarum-test （注意必须以flarum-开头）

它会在当前目录（也就是packages）下创建 test文件夹，扩展的核心就两个文件

composer.json 扩展的元信息，存储它的名字，id，关键词，作者和联系方式，版本，开源协议，图标，依赖，脚本，等等，主要是给 flarum 看的
extend.php 扩展代码的入口

由于未知原因我创建时extend.php里是这样的：namespace Sch246\\\\Test;

这应该是bug，实际上只能写namespace Sch246\Test;，改回来就好了

接下来 cd 到 flarum 根目录，将这个扩展以开发模式添加到 flarum

composer require sch246/flarum-test *@dev

只需要输入之前在 CLI 设置的 id sch246/flarum-test， composer 会自己找到扩展

仪表盘上应该出现新的扩展，启用它，刷新页面，此时 f12 打开开发者控制台，应该能看到一句 hello world

[sch246/flarum-test] Hello, admin!

具体是什么取决于打开的是后台还是前台，它来自于extend.php里导入的js/dist/forum.js或者js/dist/admin.js

而这两个 js 来自于扩展文件夹下 js/src/forum/index.ts 或 js/src/admin/index.ts 的生成

每次更改都需要 cd 进去 build 一下，然后再到根目录清除缓存以应用，挺麻烦的

cd /var/www/flarum/packages/test/js && yarn build
cd /var/www/flarum && php flarum cache:clear

按照教程修改扩展的extend.php，hello world 应该能运行

<?php

/*
 * This file is part of sch246/flarum-test.
 *
 * Copyright (c) 2024 sch246.
 *
 * For the full copyright and license information, please view the LICENSE.md
 * file that was distributed with this source code.
 */

namespace Sch246\Test;

use Flarum\Extend;
use Flarum\Frontend\Document; // 添加这一行以导入 Document 类

return [
    
    (new Extend\Frontend('forum'))
        ->content(function (Document $document) {
            $document->head[] = '<script>alert("Hello, world!")</script>';
        }),

];

如果崩溃，那么可能是语法错误或者缺少导入（比如缺少use Flarum\Frontend\Document;）

如果没有反应（包括f12控制台也没有log输出），可以检查网站源代码部分，看看里面有没有把你的代码传输过来

没有的话就是需要手动清除网站缓存，到 flarum 根目录运行php flarum cache:clear（前面有）

到这里为之可以开始开发插件了——（麻烦死了）