瓜奇（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 环境里手动执行一次初始化函数，完成数据库迁移：
guaqi_plugin_activate();
执行完之后，相关数据表才齐全。
坑 5：Node 前端的端口改了，要”重新下载”文件
前端是一份构建好的 Nuxt 产物，端口信息在构建结果里。
每次修改端口，都要回到瓜奇构建器重新下载一份 Node 端文件来替换 —— 它不是”改个配置文件就行”的普通 Node 项目。
坑 6：前端也要单独配 SSL，且建议强制 HTTPS
前后端两个域名都要装证书。
很多人只给后端配了 SSL，忘了 Node 站那个域名 —— 结果用户访问时出现混合内容（mixed content）警告，甚至部分接口直接被浏览器拦掉。
坑 7：WPGraphQL 是前置依赖，顺序不能乱
安装顺序是固定的：
- 先装并启用 WPGraphQL；
- 再装瓜奇插件。
顺序反了，GraphQL 接口注册会失败，而且报错信息不会直接告诉你”是顺序问题”。
小结：正确的部署顺序
- 解析 2 个域名（客户端 + 后端）→ 后端域名建 WP 站
- 后端配好 PHP 8.2 + Redis + swoole_loader82 → 重启 php-fpm → 设置伪静态 + SSL
- 装 WPGraphQL → 装瓜奇插件 → 手动执行
guaqi_plugin_activate() - 构建器里搭好布局 → 下载前端产物 → 部署 Node 站 → 配端口 + SSL
- 前后端域名互通测试，完成
瓜奇的部署难点不在某一步特别难，而在于步骤多、依赖链长、且出错时不告诉你错在哪。希望这篇能让下一个部署的人，把三天缩成三十分钟。
