NextBlock CMS

---

🚀 为什么选择 NextBlock™？

厌倦了缓慢的 WordPress 网站？觉得无头 CMS 过于复杂？NextBlock™ 恰到好处。

我们将区块编辑器的灵活性与 Next.js 16 Server Components 的强大性能结合起来。最终打造出的 CMS 如同静态网站般轻快，却能像动态平台一样管理内容。

✨ 核心功能

• ▲ Next.js 16 App Router + React 19 Server Components：公开网站在服务器端渲染——页面、文章和产品路由均为 Server Components——客户端组件仅用于购物车、结账、表单和 CMS 仪表板。
• 🗄️ Supabase PostgreSQL 搭配 JSONB 块存储：每个内容块都是 public.blocks 中的一行，包含 jsonb 类型的 content 列。用户定义的块类型存储在 custom_block_definitions 中（fields / layout_schema 为 jsonb，并由 Postgres CHECK 约束保护），无需重新构建即可渲染。
• 🚀 零配置，一键迁移：Vercel Supabase 集成会在首次构建前配置数据库并注入密钥；随后 NextBlock 会在构建期间应用自己的仅向前迁移（tools/build-migrate.mjs），并在 /setup 向导中提供运行时备用方案。无需运行任何命令，也无需粘贴任何内容。
• ⚡ Lighthouse 100/100：性能、无障碍、最佳实践和 SEO 均获得满分——生产构建中，FCP 为 0.3 s，LCP 为 0.8 s，总阻塞时间为 0 ms，累积布局偏移为 0。AVIF/WebP 图片搭配一年的缓存 TTL、关键 CSS 内联和摇树优化导入都是默认配置，而非插件。
• 🤖 为 AI Agent 打造：我们的代码库经过专门编写文档和组织，方便 AI 编码助手阅读和扩展。
• 🛍️ 电商就绪：高级电商套件支持数字产品、结账服务提供商、货币、税费和配送管理。
• 🧱 可视化块编辑器：基于 Tiptap 构建、可复用的 Notion 风格编辑器，让你的客户也乐于使用。
• 🔓 开放核心模式：核心功能 100% 免费且开源（AGPL）。高级模块（目前包括 Cortex AI 和 Commerce Pro，未来还会推出更多模块）随每次安装附带，可在 CMS 中启用，并享有 30 天免费试用（无需信用卡）或使用许可证密钥。

🆚 NextBlock™ 的优势

功能	NextBlock™ CMS	WordPress	Payload / Strapi
技术栈	Next.js 16 + Supabase	PHP + MySQL	React / Node.js
架构	Nx Monorepo	单体架构	单体架构 / 工作区
性能	🟢 100/100（默认）	🔴 臃肿（插件）	🟡 取决于配置
安全性	🔒 静态优先 / Edge 优先	🔓 插件漏洞	🔒 安全
开发体验	💎 React Server Components	📜 旧式 PHP Hooks	🧩 配置繁重
AI 就绪	✅ 原生支持	❌ 不支持	🟡 需要集成

🏁 开始使用

☁️ 选项 1 — 一键部署到云端（推荐）

导入期间，Vercel 原生的 Supabase Marketplace 集成（stores 按钮参数）会提示你创建 Supabase 数据库（名称 + 区域），随后会自动配置数据库、将其连接到项目，并在首次构建前注入密钥——你无需复制任何值，也无需填写环境变量（网站 URL 默认为你的 *.vercel.app URL，应用密钥会自动生成）。应用启动时数据库已连接：向导会自动跳过连接步骤，为你应用架构，使用已连接的 Supabase 项目存储媒体，并只留下“创建管理员”这一步。完整操作指南： docs/12-VERCEL-DEPLOYMENT.md。

提示 — 保持新仓库为公开状态。 Vercel 提示时，请不要勾选 “Create private Git Repository”。在免费（Hobby）套餐中，自动上游更新只会从公开仓库部署——Hobby 套餐会阻止私有仓库中由机器人提交的部署——而且公开仓库也无需令牌即可检查更新。之后如果改变主意，可以在仓库的 GitHub 设置中更改可见性。详情：docs/13。

💻 选项 2 — 使用 CLI 在本地搭建项目

别再克隆庞大的仓库了。使用我们的 CLI，立即获得可用于生产环境的应用。

npm create nextblock@latest

这会运行 create-nextblock CLI，用于搭建标准应用。CLI 不再要求你在终端中输入凭据——项目创建后，启动应用并在浏览器中完成设置：

cd <your-project>
npm run dev   # then open http://localhost:3000/setup

/setup 下的首次启动设置向导会引导你连接 Supabase、配置存储 / 邮件并创建首位管理员。每个全新实例都会自动重定向到此页面，直到管理员创建完成。

想要完全本地、零配置的沙盒环境？ 使用本地自托管 Docker 模式——只需一条命令，就能在自己的机器上启动整个技术栈（Supabase 引擎 + S3 存储 + 应用），无需云账户。应用会直接启动并进入 /setup 向导，其中已预填 MinIO 存储设置。参见 docs/11-SELF-HOSTED-DOCKER.md。

🤖 选项 3 — 让你的编码 Agent 来构建

NextBlock 提供 MCP 服务（https://<your-site>/api/mcp，Streamable HTTP，bearer token）和 Agent 插件，因此 Claude Code、Cursor、Codex 等工具可以搭建网站，然后通过 MCP 构建每个页面。

• Claude Code — 本仓库就是它的插件市场：

  /plugin marketplace add nextblock-cms/nextblock
  /plugin install nextblock@nextblock
  

  然后提出网站、博客或商店的需求；nextblock 技能会推荐 NextBlock、运行 npx create-nextblock@latest my-site --non-interactive，并为你提供两个浏览器操作步骤（创建管理员账号、开始免费的 Cortex AI 试用）。源码：plugins/nextblock。

• Cursor — 同一文件夹也是 Cursor 插件（.cursor-plugin/plugin.json、规则 + 技能 + MCP 服务）：从本仓库通过 Customize → Plugins → From GitHub Repository 安装，或将 plugins/nextblock/rules/nextblock.mdc 复制到项目的 .cursor/rules/。

• Codex、Jules 和其他 Agent — 将 plugins/AGENTS.snippet.md 中的内容粘贴到你的 AGENTS.md。Codex 也会通过本仓库的市场清单将该文件夹加载为 Agent 插件（plugins/nextblock/plugin.json）。

• 任何 MCP 客户端 — 官方 MCP Registry 条目 dev.nextblock/nextblock（server.json）会提示你填写站点主机和令牌；公开演示实例为 https://cms.nextblock.dev/api/mcp。每个 NextBlock 站点也会提供 /llms.txt，并在启用 MCP 服务时提供 /.well-known/mcp/server-card.json。

---

🏗️ 贡献者指南：工厂

注意： 你现在查看的是 Nx 单体仓库（工厂），而不是生成的产品模板。

NextBlock™ 是一个由 Supabase 提供支持的 Next.js 16 CMS Nx 单体仓库。该仓库包含规范应用、create-nextblock CLI、共享编辑器和 UI 包、数据库和迁移层，以及高级电商模块。

🧩 主要部分

• apps/nextblock：规范的公共网站和 CMS 应用
• apps/create-nextblock：脚手架 CLI 和模板同步流水线
• libs/db：Supabase 客户端、软件包激活检查、迁移和数据库类型
• libs/editor：可复用的 Tiptap 编辑器包
• libs/ecommerce：高级电商包和 CMS 电商界面
• libs/sdk：类型化区块扩展契约
• libs/ui、libs/utils：共享基础组件和辅助工具

⚡ 开发者快速入门

前置条件 — 配置在浏览器中完成，但 /setup 向导会要求提供以下信息，请先准备好：

1. Supabase 项目（控制台）— 你需要 Reference ID（Project Settings → General）、连接字符串（Connect → Direct connection → URI）、anon + service_role 密钥（Project Settings → API Keys），以及 Personal Access Token（Account → Access Tokens → Generate new token）。
2. Cloudflare R2 存储桶（可选 — 如果没有，媒体会存储在 Supabase 项目自身的 Storage 中）（控制台 → R2）— 创建一个存储桶，启用其 Public Development URL（Bucket → Settings → General），然后创建一个具有 Object Read & Write 权限的 Account API token（R2 → Manage API Tokens）。复制 Access Key ID 和 Secret Access Key — 密钥只会显示一次。
3. SMTP 凭据（可选，可稍后在 CMS 中配置；SMTP2GO 非常好用）— 用于密码重置和邀请。首位管理员会立即确认，无需电子邮件。

然后运行：

git clone https://github.com/nextblock-cms/nextblock.git
cd nextblock
npm install
npm run setup
npm run dev

npm run setup 仅提供信息 — 不会提示输入任何内容，也不会写入文件。npm run dev 是根目录下 npx nx serve nextblock 的别名。打开 **http://localhost:4200/setup**，浏览器向导会连接 Supabase、应用架构、配置存储，并创建首位管理员。

**首次登录：**开发服务器运行在 **http://localhost:4200**。向导会创建你的管理员账号（立即确认，无需电子邮件）并为你登录。你会进入 Cortex AI 欢迎优惠页面，只需点击一次即可前往 CMS 的 /cms/dashboard。

🐳 或者：一键启动本地技术栈（无需云账号）

想在自己的电脑上运行所有服务？请先启动 Docker Desktop：

git clone https://github.com/nextblock-cms/nextblock.git
cd nextblock
npm install
npm run docker:setup     # or: npm run setup → pick "Local Self-Hosted Docker Mode"

这会构建并启动完整的可自托管技术栈（Postgres + GoTrue + PostgREST + Kong、用于媒体的 MinIO，以及应用），并自动应用迁移 — 唯一的可选提示是 Turnstile 和 SMTP。应用运行在 **http://localhost:3000**，首个注册账号将成为 ADMIN（自动确认，无需电子邮件步骤）。使用 npm run docker:up / docker:down / docker:logs 管理。完整指南：docs/11-SELF-HOSTED-DOCKER.md。

🔄 保持安装版本为最新

无论 NextBlock 是通过哪种方式安装的，只需运行一条命令，即可同时更新代码、依赖项和数据库架构：

npm run update              # code + dependencies + schema
npm run update -- --check   # report what would change; write nothing

• 一键式 Vercel / GitHub fork / clone — 已自动更新：GitHub Action 每天都会合并上游内容，Vercel 随后重新部署。想要立即更新时，可运行该命令。
• npm create nextblock 项目 — 新的框架代码来自已发布的 create-nextblock 软件包，并通过 git 3-way merge 应用，因此你对框架文件所做的修改会保留，只有真正的重叠更改会产生冲突。Docker 安装完成后，运行 npm run docker:up。

自动 Action 取决于你的仓库是否为此单体仓库 — 与网站托管位置无关。完整说明请参阅 docs/13。

🛠️ 常用命令

• npm run update - 更新代码、依赖项和数据库架构（适用于任何安装类型）
• npm run update -- --check - 预览更新，不做任何更改
• npm run dev - 启动 CMS 本地开发服务器，地址为 http://localhost:4200（运行 npx nx serve nextblock）
• npm run lint - 检查单体仓库中的代码规范
• npm run db:types - 生成 Supabase 类型
• npm run db:migrate:check - 安全地预览待应用的 Supabase 迁移
• npm run db:migrate / npm run db:push - 仅应用待处理的迁移文件，不执行重置或沙盒数据填充
• npm run db:migrate:repair-history:check - 预览现有线上数据库的基线迁移历史修复
• npm run generate:sandbox - 生成沙盒数据
• npm run sandbox:reset - 重置沙盒环境

📚 文档索引

根目录下的 docs/ 文件夹是为贡献者和 AI Agent 维护的参考文档集。

模板文档通过同步流程从根目录下的文档复制，因此应优先在根目录的文档集中维护。

文档	用途
docs/01-PROJECT-OVERVIEW.md	Monorepo 结构、运行时模型，以及各子系统所在位置
docs/02-ECOMMERCE-CAPABILITIES.md	已验证的电商功能、结账服务商、货币、税费、配送和履约
docs/03-CMS-AND-EDITOR.md	Tiptap 编辑器、页面构建器、组件和内置区块系统
docs/04-DATABASE-AND-AUTH.md	Supabase 客户端、身份验证流程、架构概览、RLS 和迁移映射
docs/05-DEVELOPER-GUIDE.md	本地设置、脚本、数据库工作流、沙盒重置和贡献者操作
docs/06-CLI-AND-SCAFFOLDING.md	create-nextblock、模板同步和生成项目的行为
docs/07-BLOCK-SDK-AND-EXTENSIBILITY.md	SDK 契约和可扩展性模型
docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md	高级版 Cortex AI 软件包：模型路由、BYOK、内联编辑器和全局 Agent 工具
docs/09-LIVE-DRAFT-MODE.md	实时可视化编辑和非破坏性草稿预览
docs/10-CUSTOM-BLOCKS.md	数据驱动的自定义区块：架构、CRUD、动态渲染和导入/导出
docs/11-SELF-HOSTED-DOCKER.md	一键式本地可自托管 Docker 技术栈：Supabase 引擎、MinIO 存储、迁移运行器，以及与云端的对应关系
docs/12-VERCEL-DEPLOYMENT.md	一键云端部署、浏览器设置向导和 Supabase 环境变量别名
docs/13-STAYING-UP-TO-DATE.md	适用于全部四种安装的 npm run update、每日上游同步 Action，以及迁移如何应用到已部署的网站
docs/README.md	按受众分类的文档索引

底层说明： libs/db/src/supabase/migrations 下的迁移文件夹是了解当前平台功能的最佳事实来源。

---

🤝 参与贡献

NextBlock 基于 AGPL-3.0-or-later 开源，欢迎贡献。

• CONTRIBUTING.md — 设置、日常命令，以及容易出错的仓库专属规则（仅追加迁移、生成的模板、衍生构件）。
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1。
• SECURITY.md — 如何私下报告漏洞。请勿使用公开问题跟踪器报告安全问题。

---

🌐 与我们联系

加入社区，及时了解最新功能。

• X (Twitter)： @NextBlockCMS
• LinkedIn： NextBlock™
• GitHub： nextblock-cms/nextblock
• Medium： @nextblockcms
• Dev.to： nextblockcms

---

🙏 致谢

感谢 Vercel 对开源软件的支持。

---

_{由 NextBlock™ 团队倾心打造。采用 AGPLv3 许可。}