如何用 Node、React、GraphQL 与 Apollo 给 WordPress 换个现代前端？WordExpress 的最短上手路径

【免费下载链接】WordExpressWordPress using Node, React, GraphQL, and Apollo项目地址: https://gitcode.com/gh_mirrors/wo/WordExpress

WordExpress 是一个把 WordPress 前台从 PHP 模板中彻底解放出来的开源方案：它用 Node 承载服务端逻辑，用 React 渲染页面组件，用 GraphQL 统一定义数据接口，再由 Apollo 客户端在浏览器端完成数据拉取与缓存。你完全不触碰 WordPress 的主题体系，后台写文章、发图、管分类的方式却一点不用变。下文先把这套组合为什么值得折腾讲清楚，再给你一条从空目录到首屏页面的最短路径，最后聊聊跑起来之后能玩出什么花样。

动机：WordPress 的老毛病，和 WordExpress 给出的解法

写过 WordPress 主题的朋友都清楚那种别扭感：为了输出一篇文章列表，得在 PHP 模板里循环the_post()，为了拿到自定义字段又要再写一段查询；页面渲染和数据获取混在同一个文件里，越改越拧巴。WordExpress 的思路是把它拆成三层，各管各的：

• 数据层：用 GraphQL 充当统一查询入口。项目根目录的 schema/schema.js 把wordexpress-schema包里定义好的类型、连接器和解析函数组装成一份可执行的 GraphQL schema，底层直连 MySQL 里的 WordPress 数据库，表前缀、连接信息则来自settings/settings.js。
• 渲染层：前台全部交给 React。app/components/posts/下的 PostList、PostSingle、PostExcerpt 等组件，替代了原来刀耕火种的single.php、archive.php。
• 调度层：Apollo 客户端负责查询缓存与状态管理。app/apollo.js 里把 Apollo 的 reducer 和 middleware 挂进 Redux store，组件里声明gql查询就能自动拿到数据。

一句话总结它的定位：后台仍是熟悉的 WordPress，前台换成了现代 JavaScript 技术栈。这带来的直接好处是，页面交互可以做成单页应用体验，数据接口可以被任意前端复用，前端团队也能用自己熟悉的工具链去维护内容站点。

最短上手路径：从空目录到首屏页面

前置条件：其实只需要三样东西

• Node.js（项目基于 babel 编译，建议使用 v8 以上的较新稳定版本，旧版本会报语法错误）
• npm（随 Node 一起安装）
• 一个跑起来的 MySQL 服务，并已建好一个 WordPress 数据库

先用两条命令确认环境：

node -v npm -v

克隆与依赖安装

把仓库拉下来后直接安装依赖，这一步会同时装下 express、react、graphql、apollo-client、sequelize 等核心库：

git clone https://gitcode.com/gh_mirrors/wo/WordExpress cd WordExpress npm install

如果网络状况不佳，可以多等一会儿，node_modules的体积不小。装完后顺手看一下根目录的package.json，所有脚本命令都定义在betterScripts字段里。

一处配置决定成败：settings/dev.json

整个项目需要你动手改的地方其实就一处。打开 settings/dev.json，把数据库连接信息改成你自己的：

{ "public": { "uploads": "http://wordexpress.s3.amazonaws.com/", "amazonS3": true }, "private": { "wp_prefix": "wp_", "database": { "name": "wpexpress_dev", "username": "root", "password": "", "host": "127.0.0.1" } } }

重点看private这一段：database对应你本地 MySQL 的库名、账号、密码和地址；wp_prefix是 WordPress 表前缀，默认wp_，如果你的站点改过前缀，记得同步。settings/settings.js会根据NODE_ENV自动加载dev.json或prod.json，开发阶段你只关心前者即可。

启动开发服务器

在项目根目录执行：

npm run startdev

这条命令内部走的是babel-node --debug ./dev.js，并注入NODE_ENV=dev。打开 dev.js 就能看清它做了什么：用webpack-dev-middleware和webpack-hot-middleware提供热重载，同时挂载了两个接口——/graphql用于接收 GraphQL 请求，/graphiql则是可视化调试台。看到终端打印出App is now running on http://localhost:3000就说明一切正常。

首次访问与 GraphiQL 自检

浏览器打开http://localhost:3000，首页就是通过 GraphQL 从 WordPress 数据库拉取内容渲染出来的。接下来做一件很值的事：访问http://localhost:3000/graphiql，在这个交互式面板里手动跑一次查询，验证数据链路是否真的通了。举个例子，下面的查询对应 app/components/posts/PostQueries.js 里的写法：

{ posts(post_type: "post") { id post_title post_name post_content } }

能返回 JSON 数据，说明从 MySQL 到 GraphQL 的整条管线没有任何问题，后面再怎么改前端组件心里都有底。

启动失败时，优先排查这三个方向

新手在这一步卡住的概率不低，但九成以上逃不出下面三个原因：

1. 数据库没连上。MySQL 服务没启动、库不存在、用户名密码和dev.json不一致，都会导致连接报错。先在命令行里用账号密码手动连一次库，排除最基础的问题。
2. Node 版本过旧。项目大量使用 ES6 语法和 babel 预设，老版本运行时会在babel-node阶段直接抛语法错误。升级 Node 后记得重新npm install。
3. 端口 3000 被占用。改 dev.js 顶部的APP_PORT常量，或者在启动前用lsof -i:3000之类的命令查一下谁占着端口。

进阶玩法：跑起来之后，试着做这三件事

玩法一：在 GraphiQL 里"钓"出任意文章数据

别把 GraphiQL 只当检查工具，它其实是理解这套架构最好的入口。试着换post_type的参数值查询页面、文章、自定义类型，观察返回结构，你就知道前台 React 组件的数据是从哪来的了。

玩法二：给首页加一个自己的查询组件

打开 app/routes.js，可以看到路由分了三档：/走首页，:page走普通页面，post/:post走单篇文章。想新增一个"热门文章"区块，标准动作是：在 app/components/posts/PostQueries.js 里追加一个gql查询，再新建一个组件用graphql()高阶函数包一层，最后挂到 app/components/PostList/PostList.js 的渲染流程里。样式则放在同级的.scss文件中，webpack 已配置好 CSS Modules 的解析规则。

玩法三：走一遍生产构建与部署

开发模式跑通后，看看完整的发布链路。先执行npm run build，它会清空dist、用webpack.production.config.js打前端包，再通过build-server、build-schema、build-settings三个子任务把服务端代码和配置编译进dist目录。随后执行npm start启动生产服务，此时跑的是 server.js：只服务dist静态文件，并挂载了prerender-node为页面做预渲染——这对内容站的 SEO 是个关键设计，也是 WordExpress 相对纯单页应用更贴心的细节。

写在最后

WordExpress 的意义不在于"替换 WordPress"，而在于给你一条从 PHP 模板走向现代前端架构的低成本迁移路径：数据层有 GraphQL，渲染层有 React，状态管理有 Apollo，而你唯一要维护的旧世界，只剩下后台的写作体验和 MySQL 里的那张表。如果你正打算让团队里最懂 React 的同事接手一个内容站，这个仓库值得花一个下午完整跑通。

想继续深入，可以把注意力放到这几个文件上：schema/schema.js看数据层的组装方式，app/apollo.js看客户端状态管理，webpack.config.js看热重载与样式处理细节——它们基本勾勒出了这套技术栈的全部脉络。

【免费下载链接】WordExpressWordPress using Node, React, GraphQL, and Apollo项目地址: https://gitcode.com/gh_mirrors/wo/WordExpress