▲

Hexo CMS

面向 Hexo 静态博客的现代零命令行（Zero-CLI）可视化后台管理系统
Modern, High-Aesthetic Web CMS for Hexo Static Blogs Powered by React, Express, Schema Protocol & Vercel Geist Design

特性亮点 • 快速开始 • 核心架构 • 技术栈 • 贡献指南

---

📖 简介 (Overview)

Hexo CMS 是一款专为 Hexo 静态博客开发者与内容创作者打造的无命令行（Zero-CLI）可视化全栈后台管理系统。通过极具现代感与工业质感的 Vercel Geist 极客设计系统，让用户彻底告别繁琐复杂的终端命令。

在最新版本中，系统集成了 Hexo Theme Schema 可视化配置协议、Markdown 文章拖拽智能识别 H1 标题、防闪烁平滑拖拽、小屏全响应式防挤压适配 以及全流式 Hexo 编译部署，提供极致顺滑、高效安全的现代 Web CMS 体验。

✨ 特性亮点 (Key Features)

🎛️ Theme Schema 可视化配置引擎 自动 Schema 解析：读取主题 theme-schema.yaml 自动生成可视化表单。 Tag Pills 编辑器：支持关于页技能标签（Skills）胶囊交互与删除。 Object Card 列表编辑器：支持友情链接（Friends）多属性对象卡片可视化增删。 无损数组合并：深度处理 Lodash 合并逻辑，支持空数组干净清空。	✍️ 智能编辑器与拖拽解析 H1 标题自动识别提取：拖入 Markdown 文件时自动识别首行 # Title 提取为文章标题。 防闪烁平滑拖拽：防抖 Drag Counter 机制，全域文件拖拽平滑流畅。 双向同屏编辑器：Split-view 分屏联动与 Front-matter 展开抽屉。 物理文件冲突锁：实时检测物理磁盘 mtime，防止文件覆写冲突。
📱 全屏响应式适配 (Responsive) 顶栏导航横向滑动：小屏下 Tab 按钮自动横向滑动，防止文字竖排变形。 工具栏文本抗挤压：编辑器标题框与操作按钮应用 shrink-0 保护，窄屏同样美观。 自适应移动端体验：全移动端/平板设备流畅管理与操作。	🧩 插件与主题市场 CRUD 官方 API 实时提取：动态同步 hexo.io 官方插件与主题市场列表。 一键 Git Clone 与安装：免终端无痛下载主题并关联自动激活。 流式终端日志弹窗：全屏 Portal 顶层实时呈现 npm install 安装过程。
🖥️ 预览服务与一键构建部署 Hexo Server 掌控：随时【启动】/【停止】/【重启】hexo server (:4000)。 一键编译与清理：快捷触发 hexo g 与 hexo clean。 Git Commit & Push：静态文件打包一键推送至 GitHub / Gitee 远程仓库。	🔮 系统配置中心 & 代码注入 YAML AST 原生解析：基于 yaml AST 保留原有 _config.yml 的注释与格式。 自定义脚本 & 样式 (JS/CSS)：独立 CRUD 扩展文件，自动导出原生 Injector。 高优先级 Portal Toast：全局 Toast 提醒层级永不被模态框遮挡。

🚀 快速开始 (Quick Start)

方式一：独立免安装绿色版 (Node.js SEA 单二进制 - 推荐)

无需全局配置 Node.js 源码项目，直接从 GitHub Releases 下载对应平台的打包压缩包：

• Windows 用户: 下载 hexo-cms-win-x64.zip，解压后双击运行 hexo-cms.exe。
• Linux 用户: 下载 hexo-cms-linux-x64.tar.gz，解压后运行 ./hexo-cms。

启动后访问本地面板：http://localhost:4001。

---

方式二：源码运行与开发模式 (Development & Setup)

环境要求 (Prerequisites)

• Node.js: >= 18.0.0 (推荐/测试验证版本: v24.16.0)
• npm: >= 9.0.0 (推荐/测试验证版本: 12.0.1)
• Git: 必需

# 1. 克隆项目仓库
git clone https://github.com/base404/hexo-cms.git

# 2. 进入项目目录
cd hexo-cms

# 3. 安装依赖包
npm install

# 4. 启动前端与后端协同开发服务
npm start

# 5. (可选) 本地编译打包为单二进制 SEA 程序
npm run build:sea

访问本地服务地址：http://localhost:4001

---

方式三：Docker 容器运行 (Docker & Docker Compose)

适用于服务器部署或依赖隔离运行，无需在宿主机环境配置 Node.js 即可运行。

1. 使用 Docker Compose 一键启动（推荐）

# 1. 克隆项目仓库
git clone https://github.com/base404/hexo-cms.git
cd hexo-cms

# 2. 一键构建并后台启动容器
docker-compose up -d

# 3. 查看运行日志
docker-compose logs -f

2. 使用 Docker CLI 手动构建与运行

# 1. 构建 Docker 镜像
docker build -t hexo-cms .

# 2. 启动容器 (挂载宿主机博客路径至 /app/blog，映射 4001 Web/API 端口与 4000 Hexo 预览端口)
docker run -d \
  --name hexo-cms \
  -p 4001:4001 \
  -p 4000:4000 \
  -v /path/to/your/blog:/app/blog \
  -e BLOG_DIR=/app/blog \
  hexo-cms

• 管理后台访问地址: http://localhost:4001
• Hexo 预览服务地址: http://localhost:4000

🏗️ 核心架构 (Architecture)

graph TD
  User[用户 / 创作者] -->|Web UI 交互| Client[前端 React 18 + Vite]
  Client -->|REST API / Chunked Stream| Express[后端 Express.js 服务]
  
  Express -->|HexoInstanceManager| HexoCore[Hexo API 核心实例]
  Express -->|HexoServerService| ServerProcess[npx hexo server :4000]
  Express -->|BuildService| CLI[npx hexo g / clean / git push]
  Express -->|ThemeConfigApi| SchemaEngine[Theme Schema 解析引擎]
  Express -->|CustomScriptService| Injector[scripts/hexo_cms_injector.js]

  ServerProcess -->|物理落盘| Disk[source/ & _config.yml / _config.theme.yml]
  CLI -->|静态页面生成| Public[public/ 静态目录]

Loading

📁 目录结构 (Project Structure)

hexo-cms/
├── client/                   # 前端 React 源码 (Vite + TailwindCSS)
│   ├── src/
│   │   ├── components/
│   │   │   ├── Build/        # 运行构建、预览服务控制台与 Header 快捷条
│   │   │   ├── Common/       # Toast 提醒、CodeEditor、InstallConsoleModal
│   │   │   ├── Config/       # 全局配置中心、ThemeSchema 编辑器、自定义 JS/CSS
│   │   │   ├── Editor/       # SplitView Markdown 拖拽与智能 H1 标题编辑器
│   │   │   ├── Market/       # 主题市场与插件市场组件
│   │   │   └── Wizard/       # 官方 Hexo CLI 一键建站向导
│   │   ├── App.tsx           # 主框架路由与小屏响应式 Header
│   │   └── index.css         # Vercel Geist 极客设计系统通用样式
├── server/                   # 后端 Express 源码 (TypeScript)
│   ├── src/
│   │   ├── core/             # Hexo 实例管理器 (HexoInstanceManager)
│   │   ├── routes/           # REST API & 流式推流路由 (api.ts)
│   │   └── services/         # 核心服务 (Build, Server, CustomScript, Market, ThemeConfigApi)
│   └── test/                 # TDD 单元测试集 (Vitest)
├── screenshot.png            # CMS 最新控制台预览截图
├── package.json              # 项目依赖与运行脚本
└── README.md                 # 项目文档

🛠️ 技术栈 (Tech Stack)

领域	技术选择	说明
前端框架	React 18 + Vite	现代化极速构建与 UI 响应
样式系统	TailwindCSS 3	Vercel Geist Design System 极客风格
编辑器引擎	TipTap + Marked	WYSIWYG Markdown & H1 标题智能识别
** Schema 引擎**	Theme Schema Protocol	动态主题表单、Tag Pills & Object Card 渲染
后端服务	Express.js + TypeScript	强类型 Node.js REST API 与 HTTP Chunked 流
语法解析	YAML AST Parser	注释与格式无损的 YAML 解析写入
代码高亮	Highlight.js	JS/CSS 自定义扩展代码透明覆盖高亮
测试框架	Vitest	100% 绿灯 TDD 自动化单元测试

🤝 贡献指南 (Contributing)

欢迎提 PR 或 Issue 共同完善 Hexo CMS！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交变更 (git commit -m 'feat: Add some AmazingFeature')
4. 推送至分支 (git push origin feature/AmazingFeature)
5. 发起 Pull Request

📄 开源协议 (License)

本项目基于 MIT License 协议开源。

---

_{Built with ❤️ by AntiGravity Team for Hexo Creators worldwide.}