瓜奇本地开发环境：安装、开发和升级

这份说明写给第一次搭建瓜奇开发环境的人。照着顺序做，就能把 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 时，还要在插件页面开启对象缓存。

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

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

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。