【译】为什么我使用 React 重构了 WordPress？

如果你是一名前端工程师，大概率经历过这样的循环：

1. 团队决定用 React / Next.js 做官网或博客；
2. 你评估 Strapi、Payload、Contentful、Sanity、Ghost、Tina------各自都不错，但没有一个是「装完就能写、写完就能发」的完整发布平台；
3. 你 fork Next.js 博客模板，接上 Headless 后端，再自己搭媒体库、评论审核、SEO 元数据、预览模式、部署脚本；
4. 三个月后博客还没上线，你却维护了五个仓库。

过去两年 ，我把主要精力都花在这个循环上------不是周末 side project，而是 ReactPress 的核心工作。在 GitHub Issues、团队频道和发版计划里，同一模式反复出现：后端说做完了，博客还没上线，编辑还在等。

本文是我第一天就希望有人写过 的实战指南------在你再次投入 Headless 拼装之前。它讲为什么 「五仓库一周」会不断重演，我们做了什么 来缩短它，以及平台跑起来时实际长什么样。

如果你已经选了 Headless 后端、起了 Next.js 主题，却在冲刺后期还在接预览模式------后面这些内容就是写给你的。

与此同时，WordPress 依然占据全球 40%+ 的网站份额。PHP 被嘲笑「过时」，Gutenberg 被吐槽，可它仍是无数个人博主、内容团队、代理商和中小企业的默认选择。

React 已经统治前端十年，为什么仍然没有自己的 WordPress？

这不是技术能力问题，而是产品品类 问题。ReactPress 各版本的用户反馈里，同一问题反复出现：「能不能像 WordPress 一样管内容，但前台用 Next.js？」 现有答案要么只给 API，要么把 Admin 和主题焊死，要么需要 Docker + MySQL + 六个 npm 包才能写下第一段文字。

于是我们做了 ReactPress 4.0 ------面向 React 时代的开源发布平台，而不是又一个需要你自己拼装的 Headless 后端。

本文结构为 Why → What → How：

• WHY （§1--§3）：不可能三角、WordPress 的启示、React 生态缺口------为什么拼装总会失败
• WHAT（§4 + 执行摘要）：ReactPress 4.0 的定义、边界、与 Headless CMS 的对比
• HOW （§5--§19）：架构、Admin、主题、插件、部署、reactpress init

一屏版因果链见 [Why、What、How --- 因果链](#Why、What、How — 因果链)。

你将学到什么（结构化路径）

视角	章节	回答的问题
WHY	§1--§3	为什么 React 没有 WordPress------为什么 Headless 拼装总在失败
WHAT	执行摘要、§4	ReactPress 4.0 是什么------不是什么
HOW	§5--§19	怎么运作（架构）+ 怎么跑起来（CLI、Admin、主题、部署）
Then	§16--§18、结语	适合谁、路线图、两年后的结论

关键词： React CMS · Next.js CMS · WordPress alternative · React publishing platform · Open source CMS

---

Why、What、How --- 因果链

想先看完故事再深入的话，从这里读起。下文每一节都是下面表格某一行的展开。

WHY --- 因果链

步骤	发生了什么	后果
1. 需求	团队要 React / Next.js 博客，编辑体验要像 WordPress	市场等不了工程拼装三个月
2. 市场分裂	WordPress、SSG、Headless CMS 各解决一部分	团队只能在编辑、前端自由、开箱即用里三选二------不可能三角（§1）
3. React 缺口	Next.js 交付渲染，不是发布；Headless 交付 API，不是访客站	每个团队都要重做 Admin 胶水、SEO、媒体、评论、部署------五个仓库，第一篇还没发（§1.3）
4. 没学到 WordPress	WordPress 赢在单一入口 + core/theme/plugin 边界，不是 PHP（§2）	React 抄了优秀的零件 ，却没交付平台品类（§3）
5. 我们的回应	两年 Issues：「WordPress 工作流 + Next.js 交付------一条命令装完？」	我们停止优化 Headless 后端，做了一体化发布平台

一句话 WHY： React 没输在 frontend 能力------输在没交付 WordPress 占住的那个产品品类。所以团队还在为博客维护五个仓库。

WHAT --- 结果

ReactPress 4.0 是开源 React 发布平台------不是又一个要你拼装的 Headless CMS。

开箱即用	没有
CLI --- reactpress init 约 60 秒	给运营用的拖拽页面搭建器
Admin /admin/ --- 写作、媒体、审核	第一天就有 6 万个插件
NestJS REST API + Swagger + API Key	强制 Docker 或 SaaS 锁定
Next.js 主题 --- SSR/ISR、SEO 默认	PHP 兼容层
Hook 插件 --- SEO、摘要、图片任务	电商核心
Electron 桌面 --- 离线 SQLite 写作	成品移动 App

边界规则（一句话）：

Admin 管内容 · 主题管呈现 · 插件管逻辑 · API 管数据

完整定义与 Headless 对比：§4。

HOW --- 机制

怎么运作（架构）：

作者（Admin / Desktop）→ Toolkit（类型化 API 客户端）→ NestJS API + Hooks → SQLite/MySQL
                                                              ↓
                                              Next.js 主题 SSR/ISR → 访客与爬虫

四条硬边界保证可维护：Admin 不服务访客页；主题不碰数据库；Server 不 import 前端包；所有客户端只走 Toolkit。细节：§5--§11。

怎么试（60 秒）：

npm i -g @fecommunity/reactpress@beta
mkdir my-blog && cd my-blog
reactpress init

入口	URL
访客站	http://localhost:3001
Admin	http://localhost:3001/admin/
API 健康检查	http://localhost:3002/api/health

怎么运维： SEO 与 Lighthouse 默认（§12）、安全模型（§13）、VPS/Docker 部署（§14）、WordPress/Headless 迁移（§15）。第一篇逐步指南：§19。

接下来读什么

• 在选型？ 先读 WHY（§1--§3），再 WHAT（§4），再看适用矩阵（§16）。
• 这周就要落地？ 跳到 HOW（§5--§11），然后 §19 快速开始。
• 从 WordPress 或 Headless 迁移？ §15 与 ReactPress vs WordPress 指南。

---

目录

阅读建议： 先看 [Why、What、How --- 因果链](#Why、What、How — 因果链) 一屏掌握全貌。再按角色扫 WHY（§1--§3）、WHAT（§4）或 HOW（§5--§19）。

1. [Why、What、How --- 因果链](#Why、What、How — 因果链)
2. 执行摘要
3. 行业问题（WHY）
4. [WordPress 为什么成功（WHY）](#WordPress 为什么成功（WHY）)
5. [React 生态缺口（WHY）](#React 生态缺口（WHY）)
6. [ReactPress 理念（WHAT）](#ReactPress 理念（WHAT）)
7. 系统架构（HOW）
8. 眼见为实（HOW）
9. Admin：写作界面（HOW）
10. 主题系统（HOW）
11. 插件系统（HOW）
12. 桌面客户端（HOW）
13. [Headless API（HOW）](#Headless API（HOW）)
14. [SEO 与性能（HOW）](#SEO 与性能（HOW）)
15. 安全模型（HOW）
16. 部署模式（HOW）
17. 迁移路径（HOW）
18. 适用场景
19. 路线图
20. 常见问题
21. 快速开始
22. 结语

执行摘要

问题	简短回答
ReactPress 是什么？	自托管 React 发布平台：NestJS API + Vite Admin + Next.js 主题 + Hook 插件 + CLI + Electron 桌面端
是 Headless CMS 吗？	包含 Headless REST，但交付更多------访客站、Admin、扩展开箱即用
WordPress 替代？	是，适合要 WordPress 式工作流 + 现代 React/Next.js 栈的团队
多快能跑起来？	npm i -g @fecommunity/reactpress@beta → reactpress init → 约 60 秒
许可证	MIT------可 fork、自托管、商用
源码	github.com/fecommunity/reactpress
当前版本	4.0（代号 Extend）------插件、桌面、npm 主题 catalog

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

服务	地址
访客站	http://localhost:3001
Admin	http://localhost:3001/admin/
API	http://localhost:3002/api/health

---

1. 行业问题

现代内容基础设施逼你在编辑体验、前端自由度、明天就能跑的完整系统之间做取舍。

1.1 不可能三角

过去十年，内容工具分成三条路。每条都解决真问题------也都留洞。

路径 A：WordPress 式单体 CMS

WordPress 把内容管理、主题渲染、插件扩展绑在一个 PHP 运行时里。对非技术用户极其友好：装主题、加插件，就能上电商、会员、表单、SEO，不用写代码。

代价同样出名：

• 主题和插件质量参差不齐------一个烂插件就能拖垮性能或安全；
• 前端锁在 PHP 主题体系------React 团队很难复用组件库和设计系统，除非走 Headless 弯路；
• Headless 是后补的，不是默认心智；REST 能用，但常要额外插件和胶水；
• Core Web Vitals 常依赖 Redis、CDN、页面缓存插件，而不是把 SSR/ISR 当一等设计选择。

WordPress 优化的是**「不会写代码的人也能发布」------不是「用 React 写代码的人也能同样轻松发布」**。

路径 B：静态站点生成器

Hugo、Jekyll、早期 Gatsby、Astro------它们最大化构建时 HTML，Lighthouse 分数高、托管成本低。

SSG 藏着一个硬假设：内容变更 = 开发者改 Markdown + CI 重建。非技术编辑无法独立发稿。草稿、定时发布、媒体库、评论审核、多作者权限------WordPress 里日常操作，在纯 SSG 里要么没有，要么长得像 Git 工作流。

Next.js App Router 和 ISR 有帮助，但多数 setup 仍答不上三个问题：

• 文章存在哪？
• 谁能在浏览器里写，不用碰仓库？
• 上传的图片放哪？

路径 C：Headless CMS

Strapi、Payload、Directus、Sanity、Contentful------它们擅长内容 API：可定制 Schema、多渠道分发、权限。

它们通常不交付 作者期待的访客站 和日常写作 UI。

典型 Headless 上线路径：

选 Headless CMS → 定义 Schema → 忍受或定制 Admin
→ 写 Next.js 前台 → 接 API → 做 SEO / sitemap / OG
→ 配媒体存储 → 自建或买评论 → 写部署脚本
→ 培训编辑用新后台

对成熟平台团队可行。对「这周就要 React 栈博客」太重。

1.2 矛盾，一句话

路径	编辑	前端自由	开箱即用	现代性能
WordPress	✅	❌	✅	△
SSG / 裸 Next.js	❌	✅	△	✅
Headless CMS	△	✅	❌	取决于前台
目标：React 发布平台	✅	✅	✅	✅

React 在前端自由 和性能 上赢了，却没交付 WordPress 占住的完整发布平台品类。

这就是 ReactPress 存在的原因。

1.3 前端负责人的真实一周

我在多个团队里反复见过这套流程：

周一： 产品要博客 + SEO；市场必须不依赖开发者发稿。你打开技术方案，列 Strapi、Payload、Ghost、Headless WordPress。

周二： 选定 Strapi。Docker、PostgreSQL、Content Types。Admin 能用，但市场抱怨：只想发 Markdown 文章，上传一张图却要填四个字段。

周三： 开始写 Next.js 前台------路由、布局、深色模式、代码高亮。本该属于主题的工作，在产品应用里重做一遍。

周四： SEO------sitemap、Open Graph、JSON-LD、canonical URL------又三个 PR。评论？Disqus 或自建；CMS 后端默认不带。

周五： API 部署 VPS，前台 Vercel，媒体对象存储，四条 CI。市场问：「草稿在哪预览？」你答：「预览模式还在做。」

下周一： 产品问进度。你说「后端做完了」。他们问：「什么时候能发文？」

失败不在某个工具，而是没人交付完整的发布闭环------安装、写作、预览、发布、扩展。

ReactPress 瞄准这个缺口------不是只给更好的 API，而是第一次安装就能跑的一体化栈。

1.4 为什么「再做一个 Headless CMS」不够

每出一个新的 TypeScript Headless CMS，Schema 设计都会收获赞美。我们尊重这些项目------它们推动内容建模前进。

但对「这周上线团队博客」，更漂亮的 Content Type 编辑器不会减少你要写的 Next.js 页面数。

行业不缺 Headless CMS，缺的是：

1. 默认就有的生产级访客站------不是 demo 仓库；
2. 作者每天愿意打开 的 Admin------不是 Swagger 隔壁的凑合界面；
3. 扩展点------装插件，而不是 fork core；
4. 运维入口 ------doctor，而不是四十页部署文档。

四条都成立时，品类名该是 Publishing Platform（发布平台），不是 Headless CMS。ReactPress 选前者。

1.5 总拥有成本：拼装 vs 平台

Headless 拼装项目的隐性成本往往更大：

成本项	Headless 拼装（典型）	ReactPress（默认）
初始工程	2--8 周	约 60 秒跑起整机
持续维护的仓库	3--5（API、web、infra、主题、脚本）	1 个站点目录 + 可选 fork 主题
编辑 onboarding	为定制 Admin 写文档	WordPress 式 /admin/
SEO 基线	自建 sitemap、OG、JSON-LD	主题 starter + SEO 插件
离线写作	非标准	Electron 桌面 + SQLite
诊断	跨服务翻日志	reactpress doctor

当 time-to-first-article（第一篇上线时间） 比第一天无限 Schema 灵活更重要时，平台会赢。

---

2. WordPress 为什么成功

在要「React 的 WordPress」之前，先理解 WordPress 实际赢在哪------不止 PHP 和早期托管红利。

2.1 唯一入口，零决策疲劳

WordPress 用户很少在后端框架、前端栈、部署模式里做选择。下载、填数据库、/wp-admin/------一条路径。

这种「零决策」对工程师像束缚。对多数站主，选项少就是产品。

ReactPress 4.0 学这一点：npm i -g @fecommunity/reactpress@beta → reactpress init → 约 60 秒得到 API + Admin + 主题。默认不要 Docker。不用手写 .env。不用开三个终端。

2.2 Core / Theme / Plugin 边界

早期 WordPress 建立了 durable 的分层：

层	职责
Core	数据模型、Admin 框架、用户角色
Theme	访客看到什么
Plugin	横切逻辑------SEO、表单、安全、电商

这层分离带来**「换皮不换骨」和「加能力不 fork 主题」**。主题市场、插件市场随之出现。

React 项目常缺官方、社区认可的边界。Next.js 应用把 CMS、营销 UI、产品代码焊在一起。换「主题」等于重写仓库。

ReactPress 显式映射：

WordPress	ReactPress	角色
wp-admin	Admin（/admin/）	内容、媒体、设置
Theme	themes/*（Next.js）	访客 SSR/ISR 站
Plugin	plugins/*（Hooks）	服务端扩展
REST API	/api/*	Headless 访问，默认开启
---	Desktop（Electron）	本地优先写作

2.3 插件即 longevity

WordPress 有 60,000+ 插件。搜索、安装、启用------这个循环在不等 core 发版的情况下长出了扩展文明。

React「插件」多半是私有 npm 包或 fork------门槛高、不能热插拔、没有 marketplace 引力。

ReactPress 4.0 用 Hook + plugin.json、Admin 插槽、内置 SEO / 摘要 / 图片优化插件，让**「扩展而不碰 core」**成为平台原生能力。

2.4 托管民主化

WordPress 靠共享主机一键安装成功。用户第一天不该必须懂 Nginx 或 PM2。

ReactPress 默认内嵌 SQLite ，文档写 VPS/Docker 成长路径，并提供 reactpress doctor------降低「我这台机器能跑吗？」的门槛。

2.5 我们学习的与拒绝的

学习： 单一入口、主题/插件边界、作者优先工作流、数据可迁移。

拒绝： 把访客渲染和 Admin 焊进一个 PHP 主题；用插件数量掩盖架构债；第一篇就要 Docker/MySQL。

Same editing workflow. Modern Next.js delivery. 这才是与 WordPress 的准确关系------也是 2026 年 WordPress alternative 该有的意思：不是 PHP cosplay，而是在 React 上重建发布平台品类。

2.6 Gutenberg：写作 UI 是产品，不是事后补

WordPress 5.0 区块编辑器争议很大，但有一件事做对了：把写作界面当 core 产品，不是带 label 的数据库表单。

ReactPress Admin 用 Markdown------主要受众是技术团队和开发者博客------但原则一样：拖拽媒体、分类、标签、定时、评论审核、插件设置都在 Admin。

我们刻意不把 React 展示组件塞进 Admin 当「区块」。那会把主题逻辑泄漏进 core。展示组件属于主题。

2.7 数据所有权与开源

WordPress 的 GPL 传承和 MySQL 落盘模型，让迁移和自托管可信。

ReactPress 是 MIT 。SQLite 在 .reactpress/reactpress.db。备份可以是 tar czf backup.tar.gz .reactpress uploads。对搜 open source CMS 的团队，意味着可审计源码、无强制云、fork 友好。

内容是资产时，平台也必须可搬运。

2.8 WordPress 经济------对 ReactPress 的启示

WordPress 长出平行经济：

• 托管（managed WordPress）
• 主题（市场 + 定制 agency）
• 插件（免费 + 付费）
• Agency（实施 + 运维套餐）

ReactPress 4.0 路线图------npm 主题 catalog、插件 catalog、marketplace------瞄准同样的扩展经济 ，但用 npm + TypeScript + Next.js 做分发层，而不是 zip 上传到 wp-content/。

目标不是第一天克隆 ThemeForest，而是让主题和插件作者有标准、可寻址的运行时，生态引力才能积累。

---

3. React 生态缺口

「React CMS」不是空关键词。项目很多。占住 Publishing Platform 象限的很少------对编辑友好 且 对开发者友好 且 开箱即用。

3.1 定位图

方案	编辑友好	开发者友好	开箱即用
WordPress	高	低	高
ReactPress（目标）	高	高	高
Headless CMS（Strapi 等）	中	高	低
Next.js 博客模板	低	高	低
Markdown + Git（Tina、Decap）	低	高	低
SaaS 发布（Ghost、Medium）	高	不一	高

• Next.js 博客模板： 前台漂亮，没有 CMS。
• Headless CMS： API 强；Admin UX 和访客站你自己建。
• Notion / 文档 → 静态： 起草好，自定义域名和 SEO 控制弱。
• Git CMS（Tina、Decap）： 开发者原生；非技术编辑摩擦大。
• SaaS 发布（Ghost、Medium）： 闭环完整，自托管和主题自由不一。

缺口在右上角： 编辑和工程师都满意，技术栈统一在 React / Next.js。

3.2 为什么 Next.js 没自带 CMS

Next.js 是渲染和路由框架 ，不是内容平台。Contentlayer、MDX、Draft Mode------对开发者驱动 的站很好，不是日常编辑运营。

指望 Next.js bundled WordPress 式 Admin，就像指望 React bundled 数据库。框架团队正确地在各自 lane 里。

所以 Next.js CMS 成了集成问题 ：每个团队接 Headless + 定制 Admin + SEO + 部署。社区有 brilliant 的零件 ，没有标准的整机。

3.3 关键词背后的搜索意图

关键词	表面需求	深层需求
React CMS	React Admin	不要 PHP；统一栈
Next.js CMS	Next 集成	SSR SEO + 可定制前台
WordPress alternative	离开 WordPress	保留工作流，丢掉 PHP 包袱
Open source CMS	自托管	数据主权、可审计
React publishing platform	端到端	一条命令，不是五个仓库

ReactPress 回答最后一行：Publish with React. Ship like WordPress.

3.4 我们的迭代史

ReactPress 在 FECommunity 生态里演进：

时代	代号	教训
2.x	---	验证需求；包太碎
3.0	Platform	一条 CLI、约 60 秒起站；Docker MySQL 默认太重
3.1+	Toolkit	统一 API 契约；Next 14 / React 18
4.0	Extend	插件、桌面、npm 主题；SQLite 默认；CLI bundled runtime

每个版本都回应 Issues------不是 roadmap bingo。4.0 的 bundled runtime、SQLite、npm 主题、Hook 插件、Electron 桌面，都对应重复的用户故事。

3.5 landscape 对比（默认交付物）

方案	默认交付	访客站	典型摩擦
Strapi	API + Admin	无	自建 Next.js 前台
Payload	API + Admin（React）	无	同上
Sanity	API + Studio	无	SaaS 定价、vendor 路径
Contentful	API + Web App	无	企业 Headless
Ghost	API + Admin + 主题	Handlebars 主题	不是 React 栈
TinaCMS	Git / API 混合	不一	Git 冲突、偏 dev
Next.js 博客示例	示例代码	有	无 CMS；Markdown 在仓库
Headless WordPress	REST API	你建	插件/配置 sprawl
ReactPress	API + Admin + 主题 + 插件 + CLI + 桌面	Next.js SSR	插件市场还年轻

Google 「Next.js CMS」 ，多半是如何接入 Next.js 与 Headless 的教程------不是一条命令装完整 CMS。教程形状的缺口，就是产品缺口。

3.6 社区信号

讨论和 Issues 里反复出现的句子：

• 「我们已经在用 Next.js------博客不想上 PHP WordPress。」
• 「Strapi 能用，但前台花了两个周末。」
• 「有没有自托管开源方案，不是又一个组装套件？」

这是工程痛点，不是营销 copy。ReactPress 4.0 就是回应。

3.7 缺失的「默认栈」时刻

React 有默认 bundler 故事（Vite / webpack 时代）、默认框架故事（Next.js full stack）、默认 UI 故事（组件库）------但没有默认发布故事。

初级开发者问「怎么开博客？」答案分叉：

• WordPress（PHP）
• Medium / Substack（平台锁定）
• 「Fork 这个 Next 模板，Notion 当 CMS」
• 「起个 Strapi」

没有等价于 create-react-app 或 next new 的发布 答案。ReactPress 想成为：reactpress init。

3.8 框架 churn vs 平台稳定

React 团队每隔几年重写前台------Pages Router 到 App Router，CSS-in-JS 到 Tailwind，REST 到 tRPC。内容比框架 fashion 活得久。

发布平台必须把** durable 内容**（文章、媒体、URL）和可替换呈现（主题）分开。WordPress 活下来，因为主题换、文章还在。ReactPress 用 Next.js 主题 + 稳定 REST 复制这层分离------不是把整个 app 冻在一个 Next 仓库里。

---

4. ReactPress 理念

ReactPress 不只是 Headless CMS。它是面向 React 时代的开源发布平台。

4.1 一句话定义

Admin 管内容 · 主题管呈现 · 插件管逻辑
· API 管数据 · Toolkit 管契约

• 内容属于系统------文章、页面、媒体、分类、评论、设置。
• 呈现属于主题------可替换的 Next.js 应用。
• 逻辑属于插件------SEO、摘要、图片流水线，经 Hooks。
• 数据经 API 暴露------REST、Swagger、API Key。
• Toolkit 统一客户端------Admin、主题、插件 UI 共用一层类型化 HTTP。

4.2 vs Headless CMS

维度	Headless CMS	ReactPress
交付物	API（+ Admin）	API + Admin + 主题 + 插件 + CLI + 桌面
访客站	你的问题	官方 Next.js 主题；可换
上手	部署后端 → 建前台	reactpress init ~60 秒
扩展	Webhook、自定义字段	Hooks + plugin.json + Admin 插槽
栈	混合	React + Next.js + NestJS

只要 API、其他全自建？Headless 可能更轻。

要 WordPress 工作流 + React 前台 + 一条 CLI ？ReactPress 合适------JS 团队实用的 WordPress alternative。

4.3 设计原则

来自 ARCHITECTURE.md：

可维护性 → 可扩展性 → 技术契合 → 低成本

硬规则：

1. Admin 不服务访客页。 主题不服务 /admin/。
2. 所有前端只通过 Toolkit 访问 API。
3. Server 不依赖任何前端包。
4. 主题禁止直连数据库。

4.4 两类受众，两条路径

受众	目标	入口
站主	开博客、团队发布	npm i -g @fecommunity/reactpress@beta → init
贡献者	Core、主题、插件	Clone monorepo → pnpm dev

4.5 三十秒上手

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

服务	URL
访客站	http://localhost:3001
Admin	http://localhost:3001/admin/（`admin` / admin）
API	http://localhost:3002/api/health

默认 SQLite。不要 Docker。出问题跑 reactpress doctor。

4.6 「内容在系统里，前台给开发者」落地

反模式 A： 在 Admin 里嵌完整主题预览 + 全局主题 CSS------Admin 与主题耦合；换主题后台就坏。

反模式 B： 主题读 DB 连接串------杀死 Headless 路径和安全边界。

ReactPress 做法： 预览在 :3003；主题用 NEXT_PUBLIC_API_URL；变更走认证 REST。

编辑和主题开发者走并行流水线------多学科团队必需。

4.7 vs 可视化建站器

Webflow、Framer、Wix 用可视化编辑 + 托管锁定 解决发布。落地页很好；对需要 Git review 主题代码、CI 部署、API 集成 的团队太窄。

ReactPress 不是拖拽页面搭建器。它服务把代码当资产的团队------主题在 Git，插件在 monorepo，内容在 CMS。

4.8 「平台」在运维上意味着什么

平台提供：

• 稳定契约（REST + Toolkit 类型）
• 生命周期工具 （init、doctor、logs、stop）
• 扩展注册表（主题、插件）
• 有主张的默认（SQLite、官方主题、SEO 插件）
• 逃生舱（纯 Headless、自定义主题、MySQL）

CMS 后端 alone 提供 API。ReactPress 提供完整运维闭环。

---

5. 系统架构

ReactPress 4.0 用 monorepo + 多进程 ：内容管理、访客交付、API 服务解耦；Toolkit 统一契约。

5.1 架构概览

ReactPress 把呈现 （Admin、Desktop、主题、插件 UI）、契约 （Toolkit）、平台（NestJS server、CLI、数据库）分开。Admin、Desktop、主题不直连数据库------经 Toolkit 调 API。插件经 Hooks 扩展 Server。CLI 在单机或 VPS 上编排进程。

见下方包矩阵与 §5.2 创作流。

5.2 创作到交付

逐步：

1. 作者在 Admin 或 Desktop 创建内容。
2. 请求经 Toolkit 到 NestJS API。
3. 插件在 Hooks 上跑------摘要、SEO 校验、图片任务。
4. 数据写入 SQLite （默认）或 MySQL。
5. 主题拉已发布内容，SSR/ISR 渲染给访客和爬虫。

5.3 包职责矩阵

包	npm	角色	渲染	SEO
server	CLI bundled	业务、持久化、鉴权、Hooks	---	---
web	CLI bundled	Admin UI	Vite CSR	否
themes/	按主题	访客站	Next SSR/ISR	是
toolkit	@fecommunity/reactpress-toolkit	API 客户端、类型	---	---
plugins/	按插件	Hook 逻辑 + Admin 插槽	混合	插件驱动
desktop	GitHub Releases	Electron + 本地 API	加载 web/dist	否
cli	@fecommunity/reactpress	init、doctor、编排	---	---

5.4 技术选型

决策	选择	理由
API	NestJS	模块化 TS、Hook 友好
Admin	Vite + React SPA	交互密集；不需 SSR
访客站	Next.js App Router	SSR/ISR、SEO 原语
扩展	Hooks + manifest	WordPress 式心智
默认 DB	SQLite	零配置
桌面	Electron	复用 Admin SPA

5.5 运行时端口

进程	默认端口	说明
主题（访客）	3001	含 /admin/ 代理
API	3002	REST + Swagger
主题预览	3003	Admin iframe 预览
Admin（monorepo dev）	3000	独立 Vite dev server

5.6 init 后的目录

my-site/
├── .reactpress/
│   ├── config.json          # 端口、数据库、URL
│   ├── runtime/{theme-id}/  # 已安装主题副本
│   ├── plugins/{plugin-id}/ # 已安装插件
│   └── reactpress.db        # SQLite（默认）
├── .env                       # CLI 生成
└── uploads/                   # 媒体

把 .reactpress/ 想成 WordPress 的 wp-content/ + 数据库------备份：

tar czf backup.tar.gz .reactpress uploads

5.7 Toolkit：单一 API 客户端纪律

早期 3.x 各包各自 fetch → Admin 与主题字段漂移。4.0 强制 只用 Toolkit：

• OpenAPI 对齐的类型与路径
• 统一错误与 auth header
• createThemeApi、PluginContext、Admin React hooks

你失去「到处 raw axios」的自由；换来升级时更少的生产意外。

5.8 不离开平台的 Headless

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3002/api/article/headless/list?status=publish&page=1&pageSize=10"

API-only 可用于移动 App、第二站点、微服务------同一内容，多表面 。这才是 React CMS 该有的弹性。

5.9 贡献者 monorepo 地图

目录	用途
cli/	全局 CLI、进程编排、bundled runtime
server/	NestJS 模块、实体、Hook 服务
web/	Admin SPA
themes/	主题注册表 + hello-world + catalog 锚点
plugins/	插件注册表 + 内置
toolkit/	共享类型与 HTTP 客户端
desktop/	Electron main/preload、本地 API 引导

终端用户不 clone 这个。他们装 @fecommunity/reactpress 跑 init。

5.10 失败模式与边界

失败	护栏
主题绕过 API	架构 review；主题里禁止 DB driver
插件注入 Next 路由	禁止------插件是服务端
Admin 嵌业务规则	应经插件 Hooks
多个 API 客户端	Toolkit 强制

这些边界在维护三年后会像氧气------一开始可能觉得严。

---

6. 眼见为实

平台靠能不能跑，不只靠架构图。

6.1 CLI：约 60 秒从安装到上线

一次全局安装。一次 init。浏览器打开访客站和 Admin。不用 Docker pull。不用六个终端。不用手写 env。

这是 WordPress「单一入口」的教训------交付成 React + Next.js + NestJS。

6.2 访客站：搜索、评论、知识库、深色模式

官方 reactpress-theme-starter demo 含：

• 全文搜索
• 评论系统
• 知识库 / 文档导航
• 深色模式
• 响应式布局
• sitemap.xml、robots.txt、JSON-LD

6.3 Lighthouse：性能与 SEO 作为默认

官方主题 demo 可达 Performance 95 / SEO 100（生产数字取决于托管与内容）。

评估 Next.js CMS 时这很重要：你不该为 WordPress 式工作流牺牲慢的访客体验。默认主题存在，是为了证明工作流与速度可以并存。

6.4 在线 Demo

Demo	URL
生产博客	blog.gaoredu.com
主题 starter	reactpress-theme-starter.vercel.app
文档	docs.gaoredu.com

6.5 拼装前后对比

典型 Headless 拼装	ReactPress
选 CMS 后端	reactpress init
建或定制 Admin	/admin/ 已有
开发 Next.js 访客站	http://localhost:3001
调试 env / 端口 / DB	reactpress doctor

---

7. Admin：写作界面

访客看主题。作者活在 Admin。Admin 失败，平台就失败------不管 API 多优雅。

7.1 文章编辑器

Admin 提供：

• Markdown 编辑器------代码块、表格、粘贴上传图片
• 草稿 / 发布 工作流
• 分类与标签
• 页面 与知识库内容类型
• 修订历史（服务端）

7.2 媒体库

媒体集中在 uploads/，可选 OSS（服务端模块支持阿里云 OSS）。作者不该为博客配图开 FTP 或 S3 控制台。

7.3 插件面板

不用 SSH 即可安装、启用、配置插件。内置：

插件	能力
seo	slug、关键词、meta 描述 + 编辑器插槽
hello-world	发布时自动生成摘要
image-optimizer	批量 WebP 优化历史媒体

7.4 外观与主题

外观 → 主题 ------从注册表安装、在 :3003 预览、在 :3001 激活。换主题不迁移内容，只改呈现。

7.5 站点设置

站点标题、URL、API Key、评论策略、集成设置------作者和管理员共享的运维层。

7.6 评论审核

评论经 API；创建用 JWT；Markdown 解析后服务端 HTML 消毒（3.7+ 安全加固）；Admin 有审核 UI。存储型 XSS 和 spam 是平台责任，不是主题事后补丁。

7.7 默认账号警告

本地 admin / admin 仅试用。上生产前改密码；reactpress doctor 会提示常见安全遗漏。

---

8. 主题系统

主题 = 呈现。 访客看到的是可替换的 Next.js 应用。

8.1 两个来源，三层

来源

来源	origin	安装到
Local	monorepo 里 themes/{id}/	.reactpress/runtime/{id}/
npm	主题包	.reactpress/runtime/{id}/

层

层	角色
themes/	注册表------可安装什么
.reactpress/runtime/	CLI 实际运行的物化副本
数据库 + 配置	哪个主题在 3001 激活

8.2 官方主题

主题	来源	场景
hello-world	Monorepo local	学习、fork 基座
reactpress-theme-starter	npm catalog	生产------搜索、KB、评论

reactpress theme add @fecommunity/reactpress-theme-starter@1.0.0-beta.0

8.3 无 API 的 Mock 开发

npx create-next-app@latest my-blog \
  --example "https://github.com/fecommunity/reactpress-theme-starter" \
  --use-pnpm
cd my-blog && pnpm dev:mock

主题作者可不调全平台迭代 UI------设计周期更快。

8.4 主题内拉数据

import { createThemeApi } from '@fecommunity/reactpress-toolkit/theme';

const api = createThemeApi({ baseURL: process.env.NEXT_PUBLIC_API_URL });
const { data } = await api.article.list({ status: 'publish', page: 1 });

环境变量与 reactpress init 输出对齐（CLIENT_SITE_URL、API URL）。

8.5 App Router 约定

官方 starter 路由（示意）：

路由	用途
/	首页
/blog/[slug]	文章详情
/blog	文章列表
/docs/[...slug]	知识库
/search	搜索结果

可自由定制------契约是经 Toolkit 拉数据，不是固定文件夹名。

8.6 主题里的 SEO 职责

作为 Next.js CMS 访客层，主题负责：

• 爬虫拿到的 SSR/ISR HTML 完整
• 每路由 <title>、meta description、OG，来自 API 字段
• /sitemap.xml 与 robots.txt
• JSON-LD 结构化数据

Admin + SEO 插件写 元数据；主题渲染。换 SEO 策略换插件，不必 fork 主题。

8.7 主题部署模式

模式	何时
统一	API + 主题同一 VPS------reactpress init 风格
分离	主题 Vercel Edge，API VPS------经典 Jamstack
自定义	移动 App 或第二 Next 站，仅 Headless API

一个内容图，多表面------发布平台与纯 CMS 的差别。

8.8 从 WordPress 主题迁移

没有 PHP→JSX 魔法转换器。你要用 React 重写呈现------前期成本，长期收益：

• 复用设计系统组件
• UI 上 Storybook 和单测
• 可预期性能，不受未知 PHP 插件拖累

内容 经 WordPress REST 导出脚本进 ReactPress API。ReactPress 提供新前台、熟悉工作流。

8.9 主题 catalog 与版本兼容

theme.json + theme.manifest.schema.json 声明 requires: ">=4.0.0"。CLI 会拦 silently 不兼容安装。路线图 theme marketplace 加发现与评分------WordPress 主题店证明了换皮需求；我们用 npm + Next.js 分发。

---

9. 插件系统

ReactPress 4.0（代号 Extend ）把 Hook + plugin.json 做成一等扩展模型。

主题 = 呈现 · 插件 = 逻辑

9.1 生命周期

发现 → 安装 → 启用 → 配置 → （可选）卸载

• Admin → 插件 GUI
• CLI： reactpress plugin list、reactpress plugin install <id>
• Manifest： plugin.json 声明 hooks、Admin 插槽、设置 schema

9.2 注册表模型

位置	用途
plugins/	注册表------可用插件
.reactpress/plugins/	已安装副本 + 构建 dist
数据库 globalSetting	启用列表与各插件配置

激活时 HookService 加载插件模块并注册 hooks------与主题相同的三层模式。

9.3 服务端插件示例

import type { PluginContext } from '@fecommunity/reactpress-toolkit/plugin';

export function register(hooks: PluginContext['hooks'], ctx: PluginContext) {
  hooks.addFilter('article.beforePublish', async (article) => {
    if (!article.summary) {
      article.summary = article.content.slice(0, 160);
    }
    return article;
  });
}

构建：monorepo 里 pnpm run build:plugins；终端用户 reactpress plugin install。

9.4 Hooks vs Webhooks

机制	方向	能改数据	示例
Hook	进程内 inbound	是（filter）	SEO 校验、自动摘要
Webhook	出站 HTTP	否	Slack 通知、CI 触发

发布流水线：

article.service
  ├─ applyFilters('article.beforePublish')   ← 插件
  ├─ persist
  ├─ doAction('article.afterPublish')        ← 插件
  └─ webhookService.dispatch('article.published')

9.5 Admin 插槽

插件注册 UI 插槽------seo 在文章编辑器旁加字段。作者体验是 meta box，不是 scattered 设置页。

9.6 安全

• Manifest JSON Schema 校验
• 模块路径约束
• Ajv 配置校验

比「装 zip 碰运气」严------适合自托管 open source CMS。

9.7 第一个插件

Fork plugins/hello-world → 改 id → 实现 register() → pnpm build:plugins → Admin 启用。熟悉 NestJS 的团队一个下午。

WordPress hooks 今天更多；ReactPress hooks 更少但全类型、可测 ------为给自己定制的工程团队优化。

9.8 SEO 插件协作示例

seo 在 article.beforePublish 校验 slug 唯一，注入 Admin 字段，主题 SSR 读 metaTitle、metaDescription、keywords。插件写、主题读、core 保持 dumb ------理想的 React CMS + Next.js CMS 分工。

9.9 与 WordPress 插件的诚实对比

WordPress：60,000+ 插件，搜索即装经济。

ReactPress：catalog 年轻，机制 强，内置 essentials，最适合能写扩展的团队。

今天要现成电商、会员、表单 builder，WordPress 可能仍赢------见 ReactPress vs WordPress。

---

10. 桌面客户端

WordPress core 没有真正的离线优先、本地库写作对等物。ReactPress Desktop 填这个洞。

10.1 架构

Electron 壳 + 与 Web 同一套 Admin SPA------一套 UI 代码库、行为一致，比单独原生编辑器好维护。

10.2 模式

模式	场景	行为
本地（默认）	离线、无 Docker 试用	内嵌 SQLite API 在 127.0.0.1:3002
远程	生产/staging API	Admin 指向远程 REST

在 设置 → 桌面客户端 或登录页工作区面板切换。

10.3 同步

本地 → 远程 push 文章、页面和部分设置（需远程 admin JWT）。推荐：staging 验证后再推生产。

10.4 安装包

GitHub Releases 提供 macOS DMG 、Windows NSIS 、Linux AppImage（CI matrix 构建）。

pnpm dev:desktop      # monorepo 开发
pnpm build:desktop    # 安装包 → desktop/release/

文档：桌面客户端指南。

10.5 vs Notion 类编辑器

Notion、Google Docs、wiki 起草好，发布到自定义域名 Next.js 差------导出步骤、样式丢失、专有 sync。

Desktop 本地模式意味着写作 UI 就是生产 Admin ，经标准 REST 同步------接近 Obsidian 起草 + WordPress 发布，且一体化、开源。

10.6 安全注意

同步是单向 push + 凭据。在 staging 测冲突行为。当作任何 CMS 批量导入------生产前先排练。

---

11. Headless API

ReactPress 首先是发布平台 ------默认也是 Headless React CMS。任何 HTTP 客户端都能参与。

11.1 用 Swagger 探索

http://localhost:3002/api

Swagger UI 文档化路由、参数、响应形状------由 NestJS 装饰器生成。生产：https://your-api-domain.com/api。

11.2 认证

方式	场景
Session / JWT	Admin SPA 同源请求
API Key （X-API-Key）	Headless 服务器、脚本、移动

在 Admin → 设置 → API 创建 Key。Key 等同 admin 权限------仅 HTTPS、定期轮换、勿提交 git。

11.3 核心端点

方法	路径	说明
GET	/api/health	健康检查
GET	/api/article/headless/list	分页已发布文章
GET	/api/article/:id	单篇
GET	/api/page/list	页面
GET	/api/category/list	分类
GET	/api/tag/list	标签
GET	/api/comment/list	评论
GET	/api/setting/public	公开站点设置
POST	/api/article	创建文章（需 auth）

精确契约在 Swagger------此表是地图，不是 spec。

11.4 curl 示例

健康检查：

curl http://localhost:3002/api/health

已发布文章：

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3002/api/article/headless/list?status=publish&page=1&pageSize=10"

11.5 Toolkit TypeScript SDK

import { createApiClient } from '@fecommunity/reactpress-toolkit';

const client = createApiClient({
  baseURL: process.env.REACTPRESS_API_URL,
  apiKey: process.env.REACTPRESS_API_KEY,
});

const articles = await client.article.headlessList({
  status: 'publish',
  page: 1,
  pageSize: 10,
});

Admin、主题、插件、外部 App 共用一套 SDK------类型跟踪 API 演进。

11.6 纯 Headless 部署

只跑 API、不关心 bundled 主题：

• 营销站在自定义 Next 仓库
• 移动 App 消费文章
• 多品牌共享一个内容后端

你仍可用 ReactPress Admin 给编辑。只是不采用默认访客主题。

11.7 WordPress REST vs ReactPress Headless

WordPress REST 有，但 Headless 不是默认产品故事。字段形状随插件变；性能调优常仍假设 PHP 渲染。

ReactPress 从第一天就假设 Headless 消费者------list 端点、API Key、Toolkit、OpenAPI 是一等文档。

11.8 外部系统 Webhooks

进程内 Hooks 之外，Server 还会 outbound webhook（如 article.published）给 Slack、CI、搜索索引、数仓------异步集成不阻塞发布延迟。

---

12. SEO 与性能

团队选 Next.js CMS 栈，多半为了搜索可见性 和 Core Web Vitals。ReactPress 把 SEO 拆在插件（数据）和主题（渲染）。

12.1 渲染策略

层	策略	SEO 影响
Admin	CSR（Vite）	不索引------正确
主题	SSR / ISR	爬虫拿完整 HTML
API	JSON	喂主题和 Headless

12.2 内置 SEO 插件

作者在 Admin 设 slug、焦点词、meta 描述。主题输出：

• <title> 与 meta description
• Open Graph 与 Twitter cards
• Canonical URL
• JSON-LD（starter 里 Article、WebSite 等）

12.3 Sitemap 与 robots

官方主题从 API 内容生成 /sitemap.xml 和 robots.txt------不用手改 XML。

12.4 starter 主题里的性能实践

• Next.js 代码分割与图片优化
• 高流量列表可配 ISR
• 文章页最小 client JS
• 深色模式无 hydration flash（视主题而定）

Demo 上 Lighthouse 95 Performance / 100 SEO 是可达到的基线------不是每个主机都保证。

12.5 ReactPress vs WordPress SEO 插件

WordPress 常在主题相关 markup 之上 叠 Yoast 或 Rank Math。ReactPress 默认结构化 SEO 字段 + SSR 主题------标准博客和文档更少 moving parts。

12.6 国际化说明

文档站支持 en 和 zh。主题可实现 i18n 路由；内容模型经设置和自定义主题逻辑支持多站------i18n 在主题层，core 更简单。

12.7 上线前测量

1. 在 staging 主题 URL 跑 Lighthouse
2. Google Search Console 验证富结果
3. Fetch as Google / 检查渲染 HTML（不只 JSON API）
4. 确认 sitemap.xml 只列已发布 URL

---

13. 安全模型

自托管 open source CMS 必须默认安全、管理员可审计。

13.1 要点（3.7+）

• SQL 注入： 公开 list API 过滤列白名单（GHSA-wmw4-mw6x-6vfm）
• 存储型 XSS： Markdown 后消毒评论 HTML；POST /comment 需 JWT；Helmet CSP
• 报告： SECURITY.md

13.2 插件沙箱

Manifest 校验、约束 require 路径、schema 校验插件配置------比 unrestricted PHP include 降低「恶意插件」面。

13.3 API Key

等同 admin 权力。放 secrets manager；CI Key 尽量只读；团队变动时轮换。

13.4 生产清单

• 改默认 admin 密码
• 全站 HTTPS
• MySQL 凭据不进 git
• 反向代理限流
• 定期备份 .reactpress/ 和 uploads/
• 保持 @fecommunity/reactpress 更新拿安全补丁

13.5 评论攻击面

公开写端点是经典 XSS/spam 目标。服务端消毒 + auth + CSP 是平台职责------主题不该 alone「修」不安全 HTML。

---

14. 部署模式

reactpress init 面向本地和小型自托管生产。流量上来再 scale。

14.1 SQLite → MySQL

改 .reactpress/config.json 的 database.mode，apply 配置，按部署文档迁移数据。MySQL 适合并发写作者和更大目录。

14.2 Docker Compose

编排 API + 主题 + 反向代理 + MySQL------VPS 团队要可复现 infra 时好用。见 Docker 部署。

14.3 PM2 进程管理

单 VPS 上 PM2 跑 API 和主题 Node 进程------不用 Kubernetes 的简单中间态。

14.4 分离托管

组件	托管	说明
API	VPS / 容器	SQLite 或 MySQL
主题	Vercel / Netlify	NEXT_PUBLIC_API_URL 指远程
媒体	本地盘或 OSS	在 server 设置里配

经典 Jamstack + Headless------编辑仍用 ReactPress Admin。

14.5 备份

# SQLite + uploads 快照
tar czf backup-$(date +%F).tar.gz .reactpress uploads

MySQL 加 cron mysqldump。每季度测恢复------没恢复过的备份只是愿望。

14.6 CI/CD

• 主题仓库： push main 部署
• API： tag 或手动 workflow 部署
• 内容： 在 DB------除非静态导出模式，不随主题 redeploy

内容生命周期 与代码生命周期分开------又一个 WordPress 教训。

14.7 环境变量

CLI 从 .reactpress/config.json 生成 .env。除非你懂 sync 方向，别手改------reactpress config --apply 更安全。

---

15. 迁移路径

15.1 新站

npm i -g @fecommunity/reactpress@beta
mkdir my-site && cd my-site
reactpress init

到 React 发布平台 PoC 最快路径。

15.2 ReactPress 3.x → 4.0

4.0 加插件、桌面、npm 主题 catalog------无强制 breaking 配置迁移。

npm i -g @fecommunity/reactpress@beta
cd your-site
reactpress doctor

可选：启用 hello-world / seo 插件；试 reactpress-theme-starter；装桌面客户端。

指南：3.x → 4.0 迁移。

15.3 WordPress → ReactPress

资产	迁移方式
文章 / 页面	WordPress REST 导出 → 脚本 → ReactPress API
媒体	下载 uploads；重传或镜像 URL
分类 / 标签	API 映射 taxonomy
主题	Next.js 重写------规划工程时间
插件	关键逻辑重写为 ReactPress 插件

预期主题重写是主成本------不是数据模型翻译。

15.4 Strapi / 其他 Headless → ReactPress

若内容已在别的 Headless 里 shape 好，写 import 脚本打 ReactPress POST 或 DB seed。可渐进采用 ReactPress Admin，暂时并行 API 保留现有前台。

15.5 静态 Markdown 仓库 → ReactPress

很多团队把文章放 content/*.md。import 脚本经 API 建文章，保留 slug 和日期。之后编辑用 Admin 发新内容------Git-as-CMS 毕业不丢历史。

---

16. 适用场景

16.1 适用矩阵

场景	为什么适合 ReactPress
个人开发者博客	Admin + 快 Next 主题
开源文档 + changelog	知识库 + 文章同一主题
SaaS 营销站	Headless API + 自定义 Next 前台
多编辑团队	写作用 Admin，工程师维护主题仓库
离线优先作者	Desktop + SQLite + 同步
WordPress 替代评估	熟悉工作流、现代栈

16.2 用户故事

Alice --- 独立开发者

Next.js 做 side project；讨厌改个 typo 也要 git commit。reactpress init，周日下午发文，Lighthouse 绿，VPS 跑 :3001。不要 Strapi，不要 PHP。

开源维护者

文档版本化在知识库 API；release notes 当文章；同主题不同路由。贡献者 Admin 发稿；工程师在主题 Git 里保留自定义 React 组件。

市场 + 前端并行

市场在 Admin 排草稿；前端 fork theme-starter 做品牌动效；插件 Hook 在 article.afterPublish 发 Slack。没人往生产代码里 paste Markdown。

16.3 自测清单

若 ≥3 条成立，值得试：

• 主栈是 React / Next.js
• 非开发者必须能发稿
• 必须自托管开源
• 厌倦分开维护 CMS + 前台 + 部署
• 评估过 WordPress，想避 PHP
• 关心 SSR SEO 和 Core Web Vitals
• 想要离线或 local-first 写作

16.4 何时仍选 WordPress

• 需要成熟插件市场（电商、会员、复杂表单）
• 已有大量 WordPress 主题/插件投资
• 完全非技术团队依赖现成插件、不愿碰工程

诚实对比：ReactPress vs WordPress。

16.5 何时选纯 Headless

• 移动-only 产品消费内容
• 早期产品 discovery 每周改内容模型
• 已投 Strapi/Payload，只要新 Next 前台

ReactPress 在 Admin + 默认主题 + CLI 重要时亮------不是 API-only 实验。

---

17. 路线图

4.0 是可扩展基座，不是终点。

17.1 近期（4.x）

• 插件 npm catalog 与计划中的 reactpress plugin create scaffold
• Desktop 自动更新、托盘图标、全局快捷键
• 计划中的 reactpress theme create scaffold
• 主题与插件 marketplace------发现、版本、兼容提示（路线图）

17.2 中期

• 更多官方插件（spam 过滤、分析、i18n helper）
• Managed hosting 合作------WordPress 式 ReactPress 一键
• 多站 / 多租户给 agency
• 经插件 Hooks 更深 AI 写作集成

17.3 长期愿景

「React 栈默认发布方式」 应该像 WordPress 一样被脱口而出。

有人问「公司博客用什么？」答案应包含：

npm i -g @fecommunity/reactpress@beta
reactpress init

17.4 如何贡献

• 发主题到 npm catalog
• 分享 WordPress 或 Strapi 迁移脚本
• 贡献示例插件
• 带复现步骤提 Issue

React 的 WordPress 不会偶然出现------会被厌倦组装的开发者建出来。

---

18. 常见问题

ReactPress 免费吗？

是。MIT 许可证。可商用。自托管无 vendor 费。

4.0 能上生产吗？

4.0 在 npm 上以 @fecommunity/reactpress 发布（@latest 推广前可能是 @beta）。核心路径（init、Admin、API、主题、插件）已在 blog.gaoredu.com 生产使用。staging 验证；读迁移指南。

必须 Docker 吗？

默认 CLI 流程不要------内嵌 SQLite。在 .reactpress/config.json 配 embedded-docker 或外部数据库时才要 Docker/MySQL。

能用自己的前台吗？

能。Headless REST + API Key + Toolkit SDK。Fork theme-starter 或对着 /api/article 等从零建。

和 WordPress 有什么不同？

同样的 Admin 驱动发布工作流 ，但默认 Next.js 性能 、更干净的 Headless 路径 、对 JS 团队没有 PHP 主题/插件 entropy。

WordPress 替代？Headless CMS？Next.js 博客？

三者都是：自托管 WordPress 式编辑、Headless REST 给自定义 App、官方 Next 主题带强 Lighthouse 默认。

和 Strapi、Payload 怎么比？

它们主要交付内容 API 。ReactPress 交付 API + Admin + 主题 + 插件 + CLI + 桌面 ------React 发布平台，不只是后端。

能从 WordPress 迁移吗？

内容可以（脚本/REST）。主题要 Next.js 重写。呈现层要规划工程。

文档在哪？

docs.gaoredu.com------安装、架构、插件/主题开发、部署、桌面客户端。

怎么报安全 issue？

遵循 SECURITY.md。勿先在公开 Issue 发可利用细节。

要什么 Node 版本？

当前 CLI 发布需要 Node.js 20+。

支持 MySQL 吗？

支持------在 .reactpress/config.json 配置，用于超出 SQLite 的生产负载。

能只跑 API 吗？

能------Headless 消费者用 API + Admin；访客主题可选，自带 Next App 即可。

插件和主题有何不同？

主题改访客 UI 。插件经 Hooks 改服务端逻辑------SEO 规则、摘要、集成。

桌面 App 必须装吗？

不。可选，给离线/local-first 作者。Web Admin 已完整。

怎么更新？

npm i -g @fecommunity/reactpress@latest 更新 CLI；升级后 reactpress doctor；changelog 见 /blog。

---

19. 快速开始

19.1 安装 CLI

npm i -g @fecommunity/reactpress@beta

4.x 可能在 @latest 推广前用 @beta------查 npm。

19.2 初始化站点

mkdir my-blog && cd my-blog
reactpress init

19.3 验证服务

检查	命令 / URL
健康	curl http://localhost:3002/api/health
Admin	http://localhost:3001/admin/
访客站	http://localhost:3001

19.4 第一篇文章

1. 登录 Admin
2. 创建文章------标题、Markdown 正文、分类
3. 启用 SEO 插件------填 meta 描述
4. 发布
5. 在访客站查看------浏览器 devtools 确认 SSR 源码

19.5 安装官方主题（可选）

reactpress theme add @fecommunity/reactpress-theme-starter@1.0.0-beta.0

在 外观 → 主题 启用。

19.6 启用插件

插件 → 安装 → 启用 seo 和 hello-world。编辑文章------观察 SEO 插槽和发布时自动摘要。

19.7 试桌面端（可选）

从 GitHub Releases 下载，或 monorepo 里 pnpm build:desktop。

19.8 文档下一步

• 5 分钟第一个站点
• 核心概念
• 架构概览
• 插件开发
• 主题开发
• Headless API

19.9 反馈

若 reactpress init 卡住，开 GitHub Issue 并附 reactpress doctor 输出------含日志和环境，方便维护者复现。

---

20. 结语

React 改变了我们如何构建界面，却没有同等改变我们如何发布 ------不是因为开发者缺技能，而是因为行业交付了零件 ，WordPress 交付了平台。

WordPress 告诉我们，发布赢家组合：

• 唯一入口------低决策疲劳
• 清晰边界------core、theme、plugin
• 作者优先工作流------写作就是产品
• 扩展经济------稳定契约周围的市场
• 可搬运数据------自托管保持可信

ReactPress 4.0 把这些教训翻译到 React 时代：

能力	你得到什么
CLI	reactpress init 约 60 秒
Admin	WordPress 式内容运营
API	Headless REST + Swagger + API Key
主题	可替换 Next.js SSR，SEO 默认
插件	Hook + plugin.json 扩展
桌面	离线 SQLite 写作，就绪后同步
许可证	MIT 开源

我们不是承诺明天就有 6 万个插件。我们承诺机制与一体化默认，让 React 团队停止为每个博客、文档站、营销属性重建同一套五仓库拼装。

若你在搜 React CMS 、Next.js CMS 、WordPress alternative 、open source CMS 、React publishing platform------从这里开始：

npm i -g @fecommunity/reactpress@beta
mkdir my-blog && cd my-blog
reactpress init

六十秒后，打开 http://localhost:3001/admin/ 写第一篇。

Publish with React. Ship like WordPress.

两年下来，教训很直接：生态不需要又一个 Headless API------需要的是与 React 团队 ship 前台方式对齐的完整发布闭环。若你还在为博客分开维护 CMS、主题、部署仓库，本文记录了问题、架构，以及 ReactPress 4.0 选的默认。

更短 onboarding 见 5 分钟第一个站点 或 ReactPress 4.0 概览。对比矩阵、扩展 FAQ、运维 runbook 见文档 canonical 版。

---

相关链接

• GitHub --- fecommunity/reactpress
• 在线 Demo --- blog.gaoredu.com
• 主题 Demo --- reactpress-theme-starter.vercel.app
• 文档 --- docs.gaoredu.com
• 英文版
• ReactPress 4.0 指南
• ReactPress vs WordPress
• 架构概览
• 桌面客户端
• 更新日志
• 插件开发
• 主题开发
• Headless API 指南
• 安装
• 故障排查
• npm --- @fecommunity/reactpress