### [瓜奇本地开发环境安装说明](https://guaqi.com/docs/75993)

**Published:** 2026-05-08T02:21:23

**Author:** 春哥

**Excerpt:** 本文介绍如何在本地搭建瓜奇开发环境，包括 FlyEnv、PHP 8.2、MySQL/MariaDB、Redis、Node.js、pnpm、WordPress、瓜奇插件和前端源码的安装与启动流程。

## 准备环境

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

-   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
```



---