### [瓜奇本地开发环境：安装、开发和升级](https://gd.guaqi.com/doc/75993)

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

**Author:** 春哥

**Excerpt:** 从零搭建瓜奇本地开发环境，说明 WordPress 和前端如何安装、运行时插件源码放在哪里、PHP 与 Nod…

这份说明写给第一次搭建瓜奇开发环境的人。照着顺序做，就能把 WordPress 和前端跑起来，也能开发自己的插件。

PHP、数据库、Web 服务器和 Node.js 用什么工具安装都可以，不要求使用某一个环境管理软件。你只要先把 WordPress 运行环境和 Node.js 环境装好即可。当前前端源码要求 Node.js 24 或更高版本，并且需要能使用 `pnpm`。

## 一、安装前先准备好这些东西

-   一套能正常运行 WordPress 的本地环境，包括 PHP、数据库和 Web 服务器。
-   Node.js 24 或更高版本。
-   pnpm。
-   Windows PowerShell。

用什么软件搭建这些环境不重要。先确认 Node.js 和 pnpm 能用：

```
node -v
pnpm -v
```

如果提示找不到 `pnpm`，请用你自己的 Node.js 环境安装 pnpm，安装好后再继续。

## 二、下载 WordPress、瓜奇插件和前端源码

先创建一个空文件夹。下面都以 `D:\guaqitest` 为例。

```
mkdir D:\guaqitest
cd D:\guaqitest
```

在这个文件夹里执行：

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

脚本运行完成后，主要目录是：

```
D:\guaqitest\
├─ guaqi.test\                 WordPress
├─ node\client\                前端源码
│  ├─ layers\custom\           客户自定义前端代码
│  └─ runtime-plugins\         客户自己开发的插件源码
├─ setup.ps1
└─ guaqi-dev-guide.md
```

安装脚本还会自动创建一个目录链接：

```
D:\guaqitest\guaqi.test\wp-content\plugins\guaqi\runtime-plugins-dev
→ D:\guaqitest\node\client\runtime-plugins
```

这个链接的作用很简单：WordPress 和 Node.js 读取同一份插件源码。你不用手动创建 `runtime-plugins-dev`，也不要再复制一份插件进去。

## 三、创建本地 WordPress 站点

在你使用的 PHP 或 WordPress 环境工具中添加一个站点：

-   域名：`guaqi.test`
-   网站目录：`D:\guaqitest\guaqi.test`
-   开启 HTTPS，并让浏览器信任本地证书。
-   启用 WordPress 伪静态，也叫 URL Rewrite。

然后创建一个空数据库，浏览器打开 `https://guaqi.test`，按 WordPress 页面提示完成安装。

安装完成后进入 WordPress 后台，打开“设置 → 固定链接”，选择任意一种非“朴素”的结构并保存。

## 四、安装和配置 WordPress 插件

先安装并启用 **WPGraphQL**，然后启用安装脚本已经放好的“瓜奇”插件。Safe SVG 和 Redis Object Cache 可以按你的项目功能和本地环境安装；使用 Redis Object Cache 时，还要在插件页面开启对象缓存。

### 本地环境默认配置（部署后务必填写）

本地环境部署完成后，进入 WordPress 后台的“瓜奇插件设置”，将以下两项填入对应字段：

**API Secret：**`Ej0z5rZjL7Jsy3F5RkN552un59xxtrDa`

**前端网址：**`localhost:3000`

**请注意：**前端网址只填写 `localhost:3000`，不要添加 `http://` 前缀；同时确保 `D:\guaqitest\node\client\.env` 中的 `API_SECRET` 与上述 API Secret 完全一致。保存后重新启动 `pnpm dev`。

## 五、开启本地插件源码模式

如果你要开发运行时插件，需要编辑：

```
D:\guaqitest\guaqi.test\wp-config.php
```

在文件中“停止编辑”那一行前面加入：

```
define('GUAQI_RUNTIME_PLUGIN_DEV', true);
```

这个开关只用于本地插件开发。没有它，WordPress 不会读取 `runtime-plugins-dev` 里的源码。

## 六、启动前端开发模式

打开 PowerShell，执行：

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

第一次安装依赖会久一点。启动成功后打开：

```
http://localhost:3000
```

开发时必须使用 `pnpm dev`，不要直接运行 `nuxi dev`。项目会在 `pnpm dev` 启动时完成插件开发模式的初始化。

## 七、自己的代码到底放哪里

普通客户定制代码放在：

```
D:\guaqitest\node\client\layers\custom
```

从零开发一个运行时插件，源码放在：

```
D:\guaqitest\node\client\runtime-plugins\你的插件目录
```

一个最简单的插件目录大致是这样：

```
runtime-plugins\你的插件目录\
├─ manifest.json
├─ src\
│  ├─ server.js
│  └─ Example.vue
└─ wordpress\
   └─ plugin.php
```

PHP、Node 查询代码和 Vue 组件都放在这个插件目录里。WordPress 会通过前面自动创建的目录链接读取其中的 PHP 文件，所以不要把 PHP 插件源码再复制到瓜奇插件目录。

插件目录和 `manifest.json` 准备好后，完整停止一次 `pnpm dev`，再重新启动。然后到 WordPress 后台的瓜奇插件管理页，为当前前端开启这个插件。源码插件只会被发现，不会自动启用。

-   修改已有的 Vue 或 CSS 文件：通常会自动刷新页面。
-   修改 PHP 文件：刷新一次 WordPress 请求即可；如果 PHP 缓存没有自动更新，就重启 PHP。
-   新增、删除插件目录或 `manifest.json`：需要重新启动 `pnpm dev`。

## 八、以后怎么升级

升级前先停止正在运行的 `pnpm dev`，然后在 `D:\guaqitest` 中执行：

```
cd D:\guaqitest
irm https://7b2.com/guaqi-dev/upgrade.ps1 -OutFile upgrade.ps1; powershell -ExecutionPolicy Bypass -File .\upgrade.ps1
```

注意，最后是 `.\upgrade.ps1`，不是 `.upgrade.ps1`。

升级脚本会替换瓜奇插件和前端源码，但会保留：

-   `node\client\layers\custom` 中的客户定制代码。
-   `node\client\runtime-plugins` 中每一个客户插件目录。
-   WordPress 数据库、上传文件和其他 WordPress 插件。
-   WordPress 上传并安装的正式运行时插件包。

升级脚本还会重新创建 `runtime-plugins-dev` 目录链接。客户以前开发的插件不会因为升级被覆盖。

下面这些内容不会保留，升级后会重新生成或重新安装：

-   `node_modules`
-   `.nuxt`
-   `.output`
-   `.data`

`.env` 会使用新发布包里的文件。如果你自己改过 `.env`，升级前先记下改动，升级后再检查一遍。

升级完成后重新安装依赖并启动：

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

## 九、开发完成后怎么发布

打包前端：

```
cd D:\guaqitest\node\client
pnpm build
```

打包结果在 `.output`。把它部署到你的 Node.js 前端服务器，并按你自己的服务器环境启动和配置反向代理。

打包某个运行时插件：

```
cd D:\guaqitest\node\client
npm run runtime-plugin -- build D:\guaqitest\node\client\runtime-plugins\你的插件目录
```

插件 ZIP 默认生成在该插件目录的 `dist` 文件夹中。把 ZIP 上传到 WordPress 后台的瓜奇插件管理页，再为需要使用它的前端开启开关。

## 常见问题

### 提示“.upgrade.ps1 不存在”

命令写错了。PowerShell 当前目录中的文件要写成 `.\upgrade.ps1`。

### 打不开 guaqi.test

检查域名是不是 `guaqi.test`，网站目录是不是 `D:\guaqitest\guaqi.test`，本地 HTTPS 是否开启，以及 hosts 解析是否已经由你的环境工具配置好。

### WordPress 页面或 GraphQL 接口 404

检查 WordPress 伪静态是否开启，再到后台重新保存一次固定链接，并确认 WPGraphQL 已启用。

### 前端提示接口或密钥错误

检查 `.env` 中的 `API_BASE` 是否指向 `https://guaqi.test/graphql`，并确认 `API_SECRET` 与 WordPress 瓜奇设置中的值完全一致。改完后重新启动 `pnpm dev`。

### 运行时插件没有显示

依次检查：插件目录里有没有 `manifest.json`；`wp-config.php` 是否开启 `GUAQI_RUNTIME_PLUGIN_DEV`；`runtime-plugins-dev` 是否还是目录链接；是否重新启动过 `pnpm dev`；最后再到瓜奇插件管理页确认当前前端已经启用该插件。

### 改了 Vue 文件但页面没变化

确认你启动的是 `pnpm dev`，插件已经为当前前端启用。如果你刚新增或删除了 `manifest.json`，请完整停止后重新运行 `pnpm dev`。



---