配置NPM镜像（可选）
由于NPM默认使用的是国外的镜像源，可以通过以下命令将镜像源切换为国内镜像，提高下载速度：
npm config set registry https://registry.npm.taobao.org/
这将把NPM的镜像源设置为淘宝镜像。
开启 yarn 服务
以管理员身份打开命令提示符输入以下命令
corepack enable
接着输入以下命令
yarn
输入yes回车
输入 yarn -v查看 yarn 的版本
【参考教程】
3.2 安装配置Flarum Cli
Flarum CLI（命令行接口）是一个旨在简化Flarum扩展开发流程的工具。它通过自动化一些重复性任务，帮助开发者更高效地进行扩展开发。 该CLI基于create-flarum-extension项目官方化而来
主要功能包括：
- 扩展生成：快速创建Flarum扩展的基础结构，减少手动设置的繁琐。
- 代码生成：自动生成所需的代码文件，如JS组件、后端模型、序列化器等。
- 基础设施更新：保持扩展的基础设施模块（如TypeScript配置、依赖项等）最新。
- 扩展更新：轻松更新扩展以兼容Flarum的最新版本。
通过使用Flarum CLI，开发者可以专注于业务逻辑的实现，而将繁琐的配置和更新任务交给工具处理，从而提升开发效率。
| Version | Node.js | Flarum | PHP |
|---|
| 3.x | >= 18.x | >= 2.0 | >= 8.0 |
| 1.x-2.x | >= 12.x | >= 1.0 | >= 7.2 |
<center>表：Frarum Cli 版本匹配关系</center>
由于本次开发的 Frarum 版本为 1.8.9 故选择 2.X 版本的Cli工具，而该Cli工具一共有两种方法，一个是 npm 安装法，二是源代码解压安装方法，这里我选择方法一，但同时对方案二进行介绍
【方案一】（推荐）
在终端中输入npm install -g @flarum/cli@^2.0.0
【方案二】
打开GitHub下载页面 flarum/cli: A CLI helper for developing Flarum extensions.
点击 3.x 切换到 2.x 后在点击 Code，在下拉列表中点击 Download ZIP
![[Pasted image 20250308133923.png]]
下载SourceCode(Zip)
解压Zip到一个文件夹（此处我是 D:\Environment\Cli\FlarumCLI ）
添加 Cli 到环境变量
按 Win 键输入 编辑系统环境变量 ，打开该变量
在打开的窗口中点击环境变量
点击系统变量下方的 新建 按钮
输入相应参数
变量名：随便，我起的名字仅供参考
变量值：点击浏览目录，然后找到你之前解压的CLI文件夹下的bin文件即可
保存退出，要连着点三个确定才能保证完全退出
重启，新建终端，输入run，终端输出如下
【命令汇总】
Initialisation
flarum-cli init [PATH]: Generates a blank extension skeleton, including all recommended infrastructure.
Infrastructure: See the infrastructure section for more information.
flarum-cli infra [MODULE] [PATH]: Adds (or updates) infrastructure for some part of extension infrastructure. You can see all available modules by running fl-dev infra --help.
Audit: These commands help you make sure your extension is up-to-date.
flarum-cli audit infra [--monorepo] [--fix] Check that infrastructure files are up-to-date for all enabled modules.
Backend/Frontend Boilerplate Generation: These commands generate boilerplate code for different parts of an extension.
flarum-cli make model [className] [PATH] [-n|--no-interaction]: Generates a backend model, the corresponding table migration, policy, API resource, routes, frontend equivalent, and related extenders.flarum-cli make notification [className] [PATH] [-n|--no-interaction]: Generates a backend notification blueprint, the corresponding backend extender, and the frontend equivalent.flarum-cli make post-type [className] [PATH] [-n|--no-interaction]: Generates a post type, the corresponding extenders, and the frontend equivalent.
Localized text generation: This command generates a locale key-value pair for a given string.
flarum-cli make locale [key] [value] [PATH] [-n|--no-interaction]
Backend Boilerplate Generation: Generates different types of backend classes and/or extenders, ready to be used.
flarum-cli make backend model [className] [PATH] [-n|--no-interaction]flarum-cli make backend controller [className] [PATH] [-n|--no-interaction]flarum-cli make backend api-resource [PATH] [-n|--no-interaction]flarum-cli make backend command [className] [PATH] [-n|--no-interaction]flarum-cli make backend event-listener [PATH] [-n|--no-interaction]flarum-cli make backend handler [className] [PATH] [-n|--no-interaction]flarum-cli make backend integration-test [className] [PATH] [-n|--no-interaction]flarum-cli make backend job [className] [PATH] [-n|--no-interaction]flarum-cli make backend migration [name] [PATH] [-n|--no-interaction]flarum-cli make backend policy [PATH] [-n|--no-interaction]flarum-cli make backend repository [PATH] [-n|--no-interaction]flarum-cli make backend route [PATH] [-n|--no-interaction]flarum-cli make backend service-provider [className] [PATH] [-n|--no-interaction]flarum-cli make backend validator [className] [PATH] [-n|--no-interaction]flarum-cli make backend filter [className] [PATH] [-n|--no-interaction]flarum-cli make backend notification-blueprint [className] [PATH] [-n|--no-interaction]flarum-cli make backend notification-driver [className] [PATH] [-n|--no-interaction]flarum-cli make backend post-type [className] [PATH] [-n|--no-interaction]flarum-cli make backend mail-driver [className] [PATH] [-n|--no-interaction]
Frontend Boilerplate Generation: Generate frontend components/classes, ready to be used.
flarum-cli make frontend component [frontend] [className] [PATH] [-n|--no-interaction]flarum-cli make frontend modal [frontend] [className] [PATH] [-n|--no-interaction]flarum-cli make frontend model [className] [PATH] [-n|--no-interaction]flarum-cli make frontend forum-page [className] [routeName] [routePath] [PATH] [-n|--no-interaction]flarum-cli make frontend gambit [PATH] [-n|--no-interaction]flarum-cli make frontend notification [className] [PATH] [-n|--no-interaction]flarum-cli make frontend post-type [className] [PATH] [-n|--no-interaction]
Code Updates: These commands help update extensions for newer versions of Flarum.
flarum-cli update js-imports [PATH]: Adds admin/forum/common namespaces to all JS imports from flarum core.
And of course, you can always use the help command to see a list of all available commands with their descriptions:
flarum-cli help [COMMAND]
All commands can use a --no-interaction flag to proceed with default values for prompts when possible.
【报错集锦】
问题描述：执行npm install -g @flarum/cli@^3.0.0后终端产生如下报错信息
npm : 无法加载文件 D:\Environment\NodeJS\V22.14.0\npm.ps1，因为在此系统上禁止运行脚本。有关详细信息，
请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
问题分析：这个错误是因为 Windows PowerShell 默认的执行策略限制了脚本的运行
方案尝试：
方法1 - 以管理员身份修改 PowerShell 执行策略（推荐）
以管理员身份运行 PowerShell
执行以下命令：
Set-ExecutionPolicy RemoteSigned
当提示确认时，输入 “Y” 确认
方法2 - 仅为当前用户修改执行策略
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
方法3 - 临时绕过执行策略
如果你不想永久修改执行策略，可以在运行 npm 命令时使用以下格式：
powershell -ExecutionPolicy Bypass -Command "npm install -g wrangler"
方案验证：执行命令能够正常执行
问题描述：执行npm install -g @flarum/cli@^2.0.0命令后终端报错，报错信息如下
问题分析：由于目标仓库缺失 SSL 证书导致 npm install 请求被 npm 安全策略拦截
方案尝试：输入npm config set strict-ssl false禁用 npm 的 SSL 验证，在输入npm install -g @flarum/cli@^2.0.0
方案验证：目标包被正确添加
【参考链接】
安装Vscode本次不在赘述，有需要的可以参考这篇教程，我们直接进入插件安装配置以及项目创建的流程
3.3.1 安装配置PHP插件
3.3.2 安装配置JS插件
3.4. 创建开发模板
3.4.1. 前端模板
（1）创建模板
（2）测试模板
3.4.2. 后端模板
（1）创建模板
（2）测试模板
3.4.3. 扩展模板
（1）创建模板
可以在这个帖子中，看到更具体的讨论：Create Flarum Extension by FriendsOfFlarum
在 Flarum 目录下新建 一个 packages 目录，并且在该目录下新建 test 目录
为了不影响刚刚启动的 php -S 127.0.0.1:8888 服务，我们可以用 VSCode 多开终端，在新的终端中运行：
composer config repositories.0 path "packages/*"
在创建的 test 目录下以此输入以下指令
flarum-cli init
终端弹出run git init ? 输入Yes回车后弹出Package命名弹窗输入你的命名，命名原则参考下表（注意这是斜杠与后面的反斜杠不一样）
| 命名原则（小写包名） | - 包名格式：Flarum插件的package命名遵循供应商/包名的格式，其中供应商名可以是你独一无二的名字，或者直接沿用GitHub的用户名，而包名最好加上flarum-前缀，以指明此包是专门给Flarum用的。<br> <br>- 命名规范：命名应遵循Composer的命名规范，避免使用特殊字符和空格，尽量简洁明了，同时要确保包名在Composer仓库中是唯一的。 |
|---|
| 命名示范 | - 示例一：假设你的供应商名是acme，你开发了一个名为hello-world的Flarum插件，那么按照命名原则，该插件的package名应为acme/flarum-hello-world。<br> <br>- 示例二：如果你的GitHub用户名是swader，你开发了一个名为blockchain的Flarum插件，那么package名可以是swader/flarum-blockchain。 |
| 注意事项 | - 唯一性：确保你的供应商名和包名组合在Composer仓库中是唯一的，以避免与其他插件产生冲突。<br> <br>- 描述性：包名应具有一定的描述性，能够让人从名字中大致了解插件的功能 |
终端弹出Package description，这里输入你写这个插件的目的以及解决的问题
终端弹出Package namespace，输入 Package namespace 具体内容。命名规则参考下表
| 命名原则 | - Vendor：即供应商名，可以是你的名字、公司名或 GitHub 用户名等，用于标识插件的开发者。<br> <br>- ExtensionName：即插件的名称，通常以 Flarum 开头，或者直接描述插件的功能，且每个单词首字母大写（PascalCase）。 |
|---|
| 命名示范 | - 示例一：如果你的供应商名是 Acme，插件名是 HelloWorld，那么命名空间就是 Acme\FlarumHelloWorld。<br> <br>- 示例二：如果你的 GitHub 用户名是 swader，插件名是 Blockchain，那么命名空间可以是 Swader\FlarumBlockchain。 |
| 注意事项 | - 唯一性：确保命名空间在 PHP 中是唯一的，以避免与其他插件或库产生命名冲突。<br> <br>- 描述性：命名空间应具有一定的描述性，能够让人从名字中大致了解插件的来源和功能。<br> <br>- 一致性：保持命名的一致性，特别是在开发多个插件或相关项目时，方便管理和维护。 |
接下来这三项看着内容填就行
接下来的内容按照途中所示去执行就行
执行完后，你的工程项目文件夹，类似下图的文件结构
【参考链接】
（2）测试模板
上一步操作中，成功生成了插件模板，这时候他已经具备运行的基础文件，但是还需要做一点简单的改动，让他可以在 Flarum 后台中进行启用。
在项目根目录的 composer.json 文件中，为 require 字段在末尾先添加内容为"esjian/test":"*"的键值对
再到该 JSON 文件的头部添加如下内容
"repositories": [
{
"type": "path",
"url": "./packages/dev-test", // 这里得根据你插件模板所在位置填写路径，不能直接抄
"options": {
"symlink": true
}
}
],
项目根目录中运行终端，执行如下命令，注意不要少了*@dev
composer require esjian/test *@dev
浏览器输入127.0.0.1:8888，在管理员的后台控制面板中，便出现了刚刚生成的插件：
不过，当你点击开关，准备开启插件的时候，出现了一个报错：An error occurred while trying to load this page.
不要慌，我们可以去 storage/logs 文件夹中，查看报错的具体信息：
[2023-01-13 15:48:15] flarum.ERROR: InvalidArgumentException: File not found at path: flarum-ext-template\flarum\packages\flarum-ext-hamzone-tools/js/dist/admin.js......
很明显，缺少了前端所需的 dist 文件，只需前往 packages/dev-test（此处不能直接照抄，得根据实际情况进入相应文件夹） 中的 js 文件夹分别执行：
yarn install
yarn build
再次访问后台界面，即可开启插件，并获得默认输出：[hamzone/flarum-ext-hamzone-tools] Hello, admin!
至此，已经成功通过本地开发环境，运行了第一个 Flarum 插件——当然如果你插件写的是有问题的，那么就算做了上述操作An error occurred while trying to load this page.依旧会存在就像下图那样终端存在明显的报错，且右侧文件都提示你具体的报错位置时候你肯定无法正常运行插件
而这个时候你能做的就是在flarum 1.8.0的目录下打开终端输入如下命令（或者手动删除掉 vendor 下出问题的文件夹也行，这里是esjian/test），这个时候IDE的两个报错提示就会消失
composer uninstall esjian/test *@dev # 此处不能直接抄，esjian/test 可能得修改
【报错集锦】
问题描述：运行 yarn install 后终端弹出如下报错
error Error: https://registry.npm.taobao.org/yarn: tunneling socket could not be established, cause=getaddrinfo ENOTFOUND 7897
at ClientRequest.onError (C:\Users\lenovo\AppData\Local\node\corepack\v1\yarn\1.22.22\lib\cli.js:152896:17)
at Object.onceWrapper (node:events:633:26)
at ClientRequest.emit (node:events:518:28)
at emitErrorEvent (node:_http_client:104:11)
at Socket.socketErrorListener (node:_http_client:518:5)
at Socket.emit (node:events:518:28)
at emitErrorNT (node:internal/streams/destroy:170:8)
at emitErrorCloseNT (node:internal/streams/destroy:129:3)
at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
问题分析：由于 yarn 的流量是绕过系统设置的流量代理的，故就算系统设置了科学工具也无法代理科学流量造成超时，为此我们需要手动进行设置
方案尝试：终端输入如下命令，配合Clash Verge科学工具使用
yarn config set proxy http://127.0.0.1:7897
yarn config set https-proxy http://127.0.0.1:7897
方案检验：终端报错信息更改，更改如下
error Error: certificate has expired
at TLSSocket.onConnectSecure (node:_tls_wrap:1679:34)
at TLSSocket.emit (node:events:518:28)
at TLSSocket._finishInit (node:_tls_wrap:1078:8)
at ssl.onhandshakedone (node:_tls_wrap:864:12)
问题分析：error Error: certificate has expired，这通常是由于 Yarn 在尝试连接到 npm 注册表时遇到了 SSL 证书问题
方案尝试：禁用 yarn 的 SSL 校验，终端输入如下命令
yarn config set strict-ssl false
方案检验：问题成功解决，终端输出如下
4. 网站上线
4.1. 反代配置
- **步骤 4：简单配置 Flarum**
安装完成后，您需要进行一些基本配置：
1. 创建数据库（可以使用 MySQL 或 MariaDB）并配置权限。
2. 编辑 `config.php` 文件，配置数据库连接信息：
return [
'debug' => true,
'database' => [
'host' => 'localhost',
'user' => 'your_database_user',
'password' => 'your_database_password',
'dbname' => 'your_database_name',
],
'url' => 'http://your-site-url.com',
'paths' => [
'api' => 'api',
'admin' => 'admin',
],
];
- **步骤 5：运行安装向导**
通过浏览器访问您的 Flarum 安装目录，例如：
`http://your-site-url.com`
根据安装向导完成 Flarum 的安装过程，配置管理员账户、数据库等信息。
- **步骤 6：更新/安装扩展（可选）**
用 Composer 安装 Flarum 扩展（例如主题、功能扩展等）：
`composer require flarum/extension-name`
2.3.1.Apache
Flarum 附带了一个 Apache 的 .htaccess 文件 —— 记得正确地上传它。如果你在使用共享空间，确保你的空间提供商开启了 mod_rewrite。你也可能需要将下述加入到你的 Apache 配置中：
<Directory "/path/to/your/forum">
AllowOverride All
</Directory>
2.3.2. Nginx
- 下载 Nginx
- 访问 Nginx 官方下载页面：nginx: download
- 下载 Windows 版本 的 Nginx（
nginx/Windows-1.24.0）
- 解压文件
- 将下载的
.zip 文件解压到您选择的目录。例如，解压到 C:\nginx。
- 解压完成后，目录中应该包含一些 Nginx 文件和文件夹（例如
conf、logs、html 等）。
- 启动 Nginx
- 打开命令提示符窗口，进入 Nginx 的安装目录（
D:\Environment\Nginx\nginx-1.24.0）。
- 点击目录中的 nginx.exe ，会弹出一个命令行窗口，执行完命令后就会关闭，此时任务管理器中会多出一个 nginx 程序
- 如果一切配置正确，Nginx 应该启动并开始监听端口
80。您可以通过在浏览器中输入 http://localhost 或127.0.0.1来检查 Nginx 是否运行正常。
设置 Nginx 随 Windows 启动（可选）
如果您希望 Nginx 在 Windows 启动时自动启动，可以使用 Task Scheduler 设置任务，或者将 Nginx 添加到启动项中：
- 打开“任务计划程序”。
- 创建一个新的任务，设置任务名称并选择“在登录时运行”。
- 设置触发条件为“在登录时”，并选择要运行的程序为 Nginx 安装目录中的
nginx.exe。
- 为 Nginx 添加 Flarum代理配置
- 打开 Nginx 安装目录下的 nginx.conf 文件(通常在
nginx-1.24.0\conf目录下)，用#注释掉下面内容
location / {
root html;
index index.html index.htm;
}
- 在http块下方的server块中添加
include <Flarum目录>/.nginx.conf; 条目，此处我是include C:/Users/lenovo/Documents/Vscode/PHP/Flarum1.8.0/.nginx.conf;
- 点击 Nginx 安装目录中的 nginx.exe ，会弹出一个命令行窗口，执行完命令后就会关闭，此时任务管理器中会多出一个 nginx 程序
【报错集锦】
