瓜奇本地开发环境安装说明

准备环境

这份文档适合第一次搭建瓜奇开发环境的用户。你需要准备两部分环境：

• WordPress 运行环境：Nginx/Apache、PHP 8.2、MySQL/MariaDB、Redis。
• Node.js 开发环境：Node.js、pnpm。

如果你已经会自己安装这些软件，可以跳过 FlyEnv，直接用自己的环境。新手建议使用 FlyEnv。

1. 安装 FlyEnv 和必须软件

新手推荐用 FlyEnv 安装本地开发环境。请先到 FlyEnv 的官网或项目文档下载安装包，并按它的安装文档完成安装。

FlyEnv 里面至少需要安装：

• Nginx 或 Apache
• PHP 8.2，必须是 8.2 版本
• MySQL 或 MariaDB
• Redis
• Node.js
• pnpm

PHP 8.2 里必须启用这些扩展：

• opcache
• redis

如果 FlyEnv 里没有直接安装 pnpm，可以在 Node.js 安装好后打开命令行执行：

npm install -g pnpm

2. 下载 WordPress、瓜奇插件和 node 源码

先创建一个空文件夹，例如：

D:\guaqitest

进入这个文件夹后执行：

irm https://7b2.com/guaqi-dev/setup.ps1 -OutFile setup.ps1; powershell -ExecutionPolicy Bypass -File .setup.ps1

脚本会自动下载：

• WordPress 到 guaqi.test
• 瓜奇插件到 guaqi.test\wp-content\plugins
• node 源码到 node
• 本说明文档到当前文件夹

以后升级时，在同一个文件夹执行：

irm https://7b2.com/guaqi-dev/upgrade.ps1 -OutFile upgrade.ps1; powershell -ExecutionPolicy Bypass -File .upgrade.ps1

升级会完整替换瓜奇插件，并替换 node 源码。node\client\layers\custom 里的自定义文件会保留。

3. 在 FlyEnv 中创建站点

在 FlyEnv 中创建一个新站点：

• 域名：guaqi.test
• 网站目录：指向第 2 步下载出来的 WordPress 文件夹，例如 D:\guaqitest\guaqi.test
• 开启 SSL
• 设置 WordPress 伪静态

如果 FlyEnv 需要你手动选择伪静态规则，请选择 WordPress 规则。

4. 安装 WordPress

浏览器打开：

https://guaqi.test

按 WordPress 页面提示完成安装。

安装完成后进入后台，打开：

设置 -> 固定链接

选择一个非默认结构，例如“文章id”，然后保存。

5. 安装 WordPress 插件

进入 WordPress 后台，安装并启用这些插件：

• WPGraphQL
• Safe SVG
• Redis Object Cache

然后启用“瓜奇”插件。

Redis Object Cache 启用后，如果后台提示可以启用对象缓存，请按提示开启。

6. 配置瓜奇插件

进入 WordPress 后台的瓜奇插件设置页。

在“全局基础数据”中填写：

API Secret: Ej0z5rZjL7Jsy3F5RkN552un59xxtrDa
前端网址: localhost:3000

如果你的前端不是 localhost:3000，就填写你自己的前端网址。

7. 安装 VS Code 并打开项目

如果已经安装 VS Code，可以跳过安装。

用 VS Code 打开第 2 步创建的目录，例如：

D:\guaqitest

建议把整个目录加入工作区，这样可以同时看到 WordPress 和 node 源码。

8. 启动前端开发模式

打开命令行，进入 node 源码目录：

cd D:\guaqitest\node\client
pnpm install
pnpm dev

开发服务器启动后，通常访问：

http://localhost:3000

9. 打包和部署前端

开发完成后执行：

cd D:\guaqitest\node\client
pnpm build

打包完成后，把 .output 目录中的文件上传到你自己的前端站点服务器。

常见问题

打不开 guaqi.test

检查 FlyEnv 站点域名是否是 guaqi.test，网站目录是否指向 guaqi.test 这个 WordPress 文件夹，并确认 SSL 已开启。

WordPress 页面 404

检查 FlyEnv 是否设置了 WordPress 伪静态。设置好后，再到 WordPress 后台保存一次固定链接。

瓜奇接口不通

检查瓜奇插件里的 API Secret 是否填写为：Ej0z5rZjL7Jsy3F5RkN552un59xxtrDa，同时确认前端网址填写正确。

pnpm 命令不存在

先确认 Node.js 已安装，然后执行：

npm install -g pnpm