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

这份说明按安装、连接、开发、升级和发布的顺序介绍瓜奇本地环境。示例目录使用 D:\guaqitest，WordPress 域名使用 guaqi.test，前端使用 localhost:3000。

1. 准备环境

可以使用 flyenv 或其他环境管理工具，也可以分别安装 PHP、数据库和 Web 服务器。需要能够配置本地域名、WordPress 伪静态，并让 Node.js 访问 WordPress。

PHP：按下载的开发包要求选择。若该包注明 PHP 8.2，就使用 8.2；当前插件源码列出的支持版本是 8.1、8.2、8.3、8.4，不能据此文认定所有版本都只支持 8.2。加密包还需匹配的 Loader。
Node.js：当前源码要求 24 或更高版本。
pnpm：安装前先准备好。当前源码的 packageManager 声明为 pnpm@11.15.1，下载包若有不同声明，以该包为准。
PowerShell：下面的安装和升级命令用于 Windows。需要联网下载文件，并有项目目录的写入权限。
WordPress 依赖：准备 WPGraphQL、Safe SVG、Redis 服务和 Redis Object Cache。当前安装向导会检查这些依赖及 OPcache，不能把 Safe SVG 和 Redis Object Cache 一概当成可跳过项目。

在 PowerShell 中检查工具：

php -v
node -v
pnpm -v

php -v 只反映命令行 PHP。站点可能使用另一套 PHP，启用插件时还要核对环境工具中的站点版本，以及瓜奇安装向导显示的实际环境。

2. 下载 WordPress 和瓜奇开发包

为首次安装创建空目录：

mkdir D:\guaqitest
cd D:\guaqitest

下载并运行安装脚本：

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

脚本会下载 WordPress、前端开发包和瓜奇插件，并创建共享插件源码的目录链接。主要目录如下：

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 通过这个链接读取同一份运行时插件源码。不需要再复制一份 PHP 文件到瓜奇插件目录，也不要将链接替换成普通文件夹。

当前安装脚本还会调用开发包的 https:trust 命令，尝试信任 localhost 开发证书，因此运行脚本前就需要能使用 pnpm。若这里报错，应先检查下载包是否提供该命令和证书处理是否成功，不能把报错当成安装完成。

安装脚本不是升级工具：已有 node 目录时会停止；已有 WordPress 目录时虽然跳过 WordPress 下载，仍可能替换其中的瓜奇插件。不要在已有开发项目中反复运行它。

3. 创建本地 WordPress 站点

在环境工具中创建站点，域名填 guaqi.test，网站目录填 D:\guaqitest\guaqi.test。
选择与开发包匹配的 PHP 版本。可按包要求使用 PHP 8.2，但不要仅凭命令行版本判断站点已经切换成功。
配置 hosts 解析，让 guaqi.test 指向本机。环境工具若会自动配置，检查其结果即可。
配置 HTTPS 并让浏览器信任本地证书。本地域名在当前健康检查中有 HTTPS 豁免，但如果前端 API_BASE 填的是 HTTPS 地址，这个地址仍必须能够正常访问。
启用 WordPress 伪静态，也叫 URL Rewrite。
创建空数据库，打开 https://guaqi.test，按页面提示完成 WordPress 安装。
进入“设置 → 固定链接”，选择非“朴素”、不含 index.php 的结构并保存。

4. 启用插件并完成基础初始化

进入 WordPress 后台“插件”，安装并启用 WPGraphQL、Safe SVG 和 Redis Object Cache，再启用安装脚本放好的瓜奇插件。配置 Redis 连接，并在 Redis Object Cache 页面开启对象缓存。

当前健康检查接受 phpredis，也接受已经通过 Predis 正常工作的 Redis 对象缓存。仅启用缓存插件，不能证明 Redis 已经可用。

进入“瓜奇 → 初始化”。加密包先按向导处理 Loader，再运行健康检查、开始基础初始化。操作需要管理员的设置管理权限；等待初始化完成后再启动前端。

翻译、聊天 AI 和智能搜索可以稍后连接。运行时插件源码模式与 Loader 检查是不同事项，开启源码模式不能替代加密包需要的 PHP 扩展。

5. 核对前后端连接设置

在瓜奇设置中检查 API Secret 和“前端网址设置”。当前本地初始化逻辑会在识别到本地环境、且相应值为空时补入默认值；已有配置不会被默认值强行替换。

本地默认 API Secret：Ej0z5rZjL7Jsy3F5RkN552un59xxtrDa。前端 .env 中的 API_SECRET 必须完全一致。若你已经设置其他值，就让两端使用同一个值。
前端网址：示例填 localhost:3000。当前代码会把带协议的地址规范为主机和端口，并不是添加 http:// 就一定失败；关键是与实际访问的主机、端口一致，不要填写 WordPress 地址。
GraphQL 地址：检查 D:\guaqitest\node\client\.env 中的 API_BASE，示例为 https://guaqi.test/graphql。如果项目还配置了 NUXT_PRIVATE_API_BASE 或 NUXT_API_BASE，它们的优先级高于 API_BASE，也要一起核对。

后台修改后点击“保存设置”。修改前端环境变量后，完整停止并重新启动 pnpm dev，让启动过程读取新值。本地示例密钥不要直接作为正式站点的共用密钥。

6. 开启运行时插件源码模式

如果只修改普通前端页面，可以先跳过本节。开发包含 WordPress PHP 的运行时插件时，需要让 WordPress 和 Node.js 都在本机，并读取同一份源码；这套联调方式不支持线上 WordPress 搭配本地 Node.js。

编辑：

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

在“停止编辑”提示前加入：

define('GUAQI_RUNTIME_PLUGIN_DEV', true);

确认 runtime-plugins-dev 仍是指向 node\client\runtime-plugins 的目录链接。这个开关只决定 WordPress 是否发现和读取开发源码；WP_DEBUG 不能替代它。

在首次启动前端前完成以上配置。若先运行了前端、后来才开启源码模式，需要完整停止并重新运行 pnpm dev。

7. 启动前端并验证连接

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

使用项目提供的 pnpm dev。它会先加载环境并初始化开发缓存和运行时状态，再启动 Nuxt；直接执行 nuxi dev 会绕过这一步。

打开终端输出的访问地址。当前源码通常使用 http://localhost:3000；下载包若启用了 HTTPS，以终端实际输出为准，并确认开发证书受信任。

确认终端没有 GraphQL、密钥或初始化错误。
确认前端页面可以读取 WordPress 中的内容。
发布或修改一篇测试内容，检查前端是否更新。
确认后台登记的前端主机和端口与浏览器访问地址一致。

能打开一个页面不代表所有接口都正常。遇到连接错误，先检查 WordPress 是否运行、WPGraphQL 是否启用、伪静态和 API_BASE 是否正确，再核对两端密钥。

8. 把自定义代码放到正确目录

普通前端定制代码放在：

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

运行时插件放在 runtime-plugins 的直接子目录。新插件可以用当前脚手架创建：

cd D:\guaqitest\node\client
pnpm runtime-plugin create runtime-plugins/vendor-example vendor/example "示例插件"

目标目录必须尚不存在。脚手架会生成当前 Manifest v6 的基础文件，包括插件自己的 package.json、Node 入口、Vue 组件和 PHP 入口：

runtime-plugins\vendor-example\
├─ manifest.json
├─ package.json
├─ src\
│  ├─ server.js
│  └─ ExampleModule.vue
└─ wordpress\
   └─ plugin.php

PHP、Node 查询逻辑和 Vue 组件放在同一个插件目录，通过 manifest 声明入口和模块。新增组件需要显式导入，第三方依赖需要写入插件自己的 package.json；缺少这些声明会影响源码扫描或打包。

插件被发现后，进入 WordPress 后台“瓜奇 → 插件管理”，为当前前端开启它。源码插件只会被发现，不会自动启用；多个前端需要分别开启。不要通过修改 .active.json 启用插件，该文件已不参与运行。

验证时，在构建器中检查插件模块是否出现，将模块放到适用页面并查看前端效果。预览使用插件声明的 previewData，不能仅凭预览内容判断真实 WordPress 查询已经成功。

9. 修改源码后怎样生效

已有 Vue 或 CSS 文件：通常由 Vite 自动热更新。
Node 入口内部逻辑：由开发环境重载处理，观察终端是否报告错误。
PHP 文件：下一次 WordPress 请求会读取修改；如果 OPcache 不检查文件时间戳，需要重启 PHP。
manifest 或插件目录增删：当前源码已监听相关变化并重新扫描、更新开发模板，不再一概要求重启。如果下载的是未包含此监听的旧开发包，或页面仍未更新，可重新启动 pnpm dev，或在后台将插件关闭后再开启。
首次开启源码模式、修改 .env：完整停止并重新运行 pnpm dev。

如果插件没显示，依次检查 manifest 和入口声明、开发开关、目录链接、终端扫描结果，以及当前前端的启用状态。源码格式有问题时，扫描可能跳过该插件并输出原因，重启不能修好无效声明。

10. 升级已有开发环境

先手动停止这个项目的 Node.js 开发服务，并暂时停止编辑文件。在原安装根目录运行升级脚本：

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

注意当前目录文件要写成 .\upgrade.ps1，不能写成 .upgrade.ps1。当前脚本要求确认已停止服务后输入 UPGRADE；它不会替你停止或重新启动服务。

当前升级脚本保留以下内容：

node\client\layers\custom 和 node\client\runtime-plugins。
node\client\.env 及 .env.* 环境文件。
node\client\.data，以及列入保护范围的 Git 和工作目录。
WordPress 数据库、上传文件和其他 WordPress 插件。正式运行时插件包若位于瓜奇系统文件替换范围之外，也不会因替换系统文件而被删除。
已经存在且符合预期的 runtime-plugins-dev 目录链接，以及已有的 Assets\loader。

升级按新发布包中的文件制定替换计划，未列入替换计划的本地文件保留。因此，不能笼统说 node_modules、.nuxt、.output 和 .data 都会被删除；其中 .data 是明确保护项。依赖和生成文件是否需要更新，以升级后的包和启动结果为准。

脚本会在 .upgrade-backups\本次编号 保存备份、替换计划和状态，并保留 .upgrade-work\本次编号 中的下载文件。自定义源码和环境文件会先备份并校验。目录链接正确时保留，缺失时创建；链接指向异常或遇到不安全的目录链接时会停止。

升级不会切换 PHP 版本。完成后确认 PHP 仍与新插件包匹配，检查新版本是否新增环境变量要求，再安装依赖并启动：

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

如果升级失败，不要用 setup.ps1 重装来覆盖现场。保留备份和工作目录，查看备份中的 status.txt、replacement-plan.json 和 previous 目录，再按实际替换情况恢复。当前脚本不会在所有失败情况下自动回滚整个环境。

11. 打包并部署

打包自定义前端：

cd D:\guaqitest\node\client
pnpm build

构建结果位于 .output。部署完整目录，使用其中的 server/index.mjs 作为启动入口，再按服务器环境配置端口、反向代理和 HTTPS。不要只上传单个入口文件，也不要将开发服务器作为正式部署方式。

打包某个运行时插件：

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

ZIP 默认生成在该插件目录的 dist 中。使用有设置管理权限的账号，在 WordPress 后台“瓜奇 → 插件管理”上传，再为需要使用的前端开启。

正式插件包支持运行时启用、停用和更新，不需要因此重新构建整个前端。发布前仍应验证实际页面、查询和权限；本地源码热更新成功不能代替 ZIP 安装验证。生产环境不要保留用于本地联调的源码模式。

常见问题

打不开 guaqi.test

检查域名、hosts 解析、网站目录、Web 服务和证书。目录应为 D:\guaqitest\guaqi.test，不要指向其上级目录。

页面或 GraphQL 接口 404

检查服务器伪静态，重新保存非朴素固定链接，并确认 WPGraphQL 已启用。固定链接设置正确也不能替代服务器重写规则。

插件启用失败或接口报错

先按安装向导检查站点实际使用的 PHP、插件包和 Loader，再查看具体错误。不要把所有白屏或 500 都归因于“PHP 不是 8.2”。

前端提示接口或密钥错误

检查实际生效的 GraphQL 地址和环境变量优先级，确认 WordPress 与前端的 API Secret 一致、前端网址已登记。修改环境文件后重新启动 pnpm dev。

修改插件后页面没变化

确认启动命令是 pnpm dev、WordPress 已开启源码模式、目录链接正确、当前前端已启用插件。再查看终端是否跳过插件或热扫描失败；使用旧包时，按需要重启开发服务。