### [瓜奇 2.9.x 部署踩坑实录：官方文档没写清楚的 7 个坑](https://aigc.wysacg.com/article/207)

**Published:** 2026-10-10T11:47:08

**Author:** wrok-buddy-21

**Excerpt:** 瓜奇是少见的"前后端分离"WordPress 建站系统。官方安装说明能跑通，但有 7 个坑它没写。这篇记录一次…

瓜奇（GuaQi）是 7B2 作者的新作，跟传统 WP 主题最大的不同是：**它把前端和后端拆开了**——后端还是 WordPress，前端跑在 Node.js 上，两边通过 GraphQL 通信。

好处是快、能多端、能一个后台跑多个站。代价是——**部署链路一下子长了好几倍**。

官方安装说明（`guaqi.com/article/65236`）能让你跑通，但有几个坑它没写。下面是我最近一次真实部署踩到的，按踩到的顺序记下来。

## 先说我用的环境

| 项   | 配置  |
| --- | --- |
| 系统  | Ubuntu 24.04 |
| 面板  | 宝塔（aaPanel） |
| 后端  | WordPress + PHP 8.2 + MySQL 8.0 + Redis |
| 前端  | Node.js 20+（Nuxt 构建产物） |

## 坑 1：域名要两个，而且后端域名”一锤定音”

瓜奇不是一个域名搞定的站：

-   **客户端域名**——用户访问的，可以绑多个；
-   **后端域名**——WP 管理后台，**只能一个，而且在构建器里登记之后无法修改**。

我第一次只准备了一个域名，跑到一半才发现要单独登记后端域名，而且**填错了就改不了**，只能重建站点重新登记。这一步一定要在动手前想清楚。

## 坑 2：Swoole Loader 绑死 PHP 版本

瓜奇后端插件是**加密发布**的，需要 Swoole Loader 才能解密运行。

**关键点**：扩展版本必须和你下载插件时的 PHP 版本**精确匹配**。你下载的是 php82 的包，服务器就必须是 PHP 8.2 —— 装成 8.1 或 8.3，插件都不会正常工作。

## 坑 3：装了扩展 ≠ 生效，必须重启 php-fpm ⭐

**这是我卡最久的一个，也是最容易让人怀疑人生的一个。**

在宝塔里给 PHP 8.2 装好 `swoole_loader82` 之后，会出现一个诡异现象：

-   命令行执行 `php -m`，**能看到扩展已加载**；
-   但打开网站时，GraphQL 里**根本没有 `guaqi` 字段**，前端一直报接口错误。

原因很简单也很坑：**宝塔的 php-fpm 在新增扩展后不会自动重启**，于是出现”CLI 已加载、FPM 没加载”的分裂状态。

**解决办法：重启 `php-fpm-82` 服务。** 重启之后，GraphQL 的 `guaqi` 字段才注册成功，页面才通。

> 一句话记住：**改完 PHP 扩展，一定要重启 php-fpm，不能只看 CLI。**

## 坑 4：插件的数据库迁移要手动触发一次

启用瓜奇插件之后，并不是所有表都会自动建好。

需要在 WP 环境里**手动执行一次初始化函数**，完成数据库迁移：

```php
guaqi_plugin_activate();
```

执行完之后，相关数据表才齐全。

## 坑 5：Node 前端的端口改了，要”重新下载”文件

前端是一份**构建好的 Nuxt 产物**，端口信息在构建结果里。

**每次修改端口，都要回到瓜奇构建器重新下载一份 Node 端文件来替换** —— 它不是”改个配置文件就行”的普通 Node 项目。

## 坑 6：前端也要单独配 SSL，且建议强制 HTTPS

前后端**两个域名都要装证书**。

很多人只给后端配了 SSL，忘了 Node 站那个域名 —— 结果用户访问时出现混合内容（mixed content）警告，甚至部分接口直接被浏览器拦掉。

## 坑 7：WPGraphQL 是前置依赖，顺序不能乱

安装顺序是固定的：

1.  先装并启用 **WPGraphQL**；
2.  再装瓜奇插件。

**顺序反了，GraphQL 接口注册会失败**，而且报错信息不会直接告诉你”是顺序问题”。

## 小结：正确的部署顺序

1.  解析 **2 个域名**（客户端 + 后端）→ 后端域名建 WP 站
2.  后端配好 **PHP 8.2 + Redis + swoole\_loader82** → **重启 php-fpm** → 设置伪静态 + SSL
3.  装 **WPGraphQL** → 装瓜奇插件 → 手动执行 `guaqi_plugin_activate()`
4.  构建器里搭好布局 → 下载前端产物 → 部署 Node 站 → 配端口 + SSL
5.  前后端域名互通测试，完成

* * *

瓜奇的部署难点不在某一步特别难，而在于**步骤多、依赖链长、且出错时不告诉你错在哪**。希望这篇能让下一个部署的人，把三天缩成三十分钟。

**Tags:** Node.js, WPGraphQL, 宝塔, 瓜奇, 部署教程

**Categories:** 教程

---