常见问题 FAQ
安装与入门
我需要 Docker 吗？
默认不需要。 reactpress init 使用嵌入式 SQLite，桌面客户端同样无需 Docker。
仅在 .reactpress/config.json 中配置 embedded-docker 或外部 MySQL 时才需要 Docker / 独立数据库服务。
init 和 dev 有什么区别？
4.0 全局 CLI 中，init 已包含启动服务，无需再执行 dev。dev 在全局 CLI 中已移除；Monorepo 贡献者使用 pnpm dev。
Admin 地址是 3000 还是 3001/admin？
reactpress init 默认：http://localhost:3001/admin/（Admin 挂载在访客主题同端口）。
Monorepo 本地开发时，Admin Vite dev server 可能在 http://localhost:3000。
默认账号是什么？
首次 bootstrap：admin / admin。请登录后立即修改密码；生产环境在 .env 或 Admin 中更新。
功能与选型
可以用自己的前端吗？
可以。ReactPress 提供 Headless REST + API Key。可 fork reactpress-theme-starter 或自行对接 /api/article 等端点。见 Headless API 指南。
和 WordPress 有什么不同？
相同点：Admin 驱动的内容工作流、主题与插件扩展。
不同点：默认 Next.js 主题更快、Headless 路径更清晰、无 PHP 主题包袱；另提供 Electron 桌面离线写作。
和 Strapi / Payload 等 Headless CMS 比呢？
它们主要交付后端 API；ReactPress 交付完整发布平台（Admin + API + 主题 catalog + 插件 + 桌面），一条 CLI 即可运行，减少组装成本。
适合做什么类型的站？
个人博客、团队知识库、开发者文档站、营销站 + Headless 定制前端、需要离线写作的工作流等。见 介绍 中的场景表。
能从 WordPress 迁移吗？
内容可通过导出脚本或 Headless REST API 对接；PHP 主题无法直接迁移，需在 Next.js 中重建访客前端，或使用 reactpress-theme-starter。见 Headless API 指南 与 ReactPress vs WordPress。
ReactPress 免费吗？
是，MIT 开源。全局安装：npm i -g @fecommunity/reactpress@beta。
版本与升级
4.0 可以上生产吗？
4.0 处于 active beta。建议在升级生产前阅读 3.x → 4.0 迁移 并在 staging 验证。核心路径 init / doctor 已稳定可用。
如何从 3.x 升级到 4.0？
见 迁移指南。4.0 无强制 Breaking，插件与桌面为增量能力。
@fecommunity/reactpress-server 还能用吗？
已 deprecated。新项目请使用 @fecommunity/reactpress CLI bundled API，或 Monorepo 源码部署。
部署与配置
生产环境 .env 怎么填？
将 CLIENT_SITE_URL 改为访客站公网域名，SERVER_SITE_URL 改为 API 公网域名（含协议，无尾部斜杠）。数据库凭据与本地类似或使用托管 MySQL。详见 项目配置项。
数据库连不上怎么办？
- 运行
reactpress doctor - 检查
.env与config.json是否一致 - Docker MySQL 是否运行：
pnpm docker:dev:status - 见 故障排查
端口被占用怎么办？
reactpress doctor 会列出占用进程。可修改 config.json 中 server.port / client.port 后 config --apply（Monorepo），或停止冲突进程。
主题与插件
访客站空白 / 404？
通常在 Admin 外观 → 主题 中安装并启用主题。未启用时 API 可能正常但 :3001 无主题进程。
插件改了不生效？
Monorepo 开发需 pnpm run build:plugins 后重启 API。确认 Admin 中插件已启用，并检查 Hook 名是否与 plugin.json 一致。
获取帮助
reactpress doctor与reactpress logs- GitHub Issues
- GitHub Discussions
提问前请阅读 提问的智慧，附上 Node 版本、操作系统、doctor 输出与相关日志。