Lumos - 基于 Bun 的高性能静态博客生成器

Lumos 是一个现代化的静态博客生成器，基于 Bun 运行时构建，采用 TypeScript + React + JSX 的技术栈，为开发者提供高性能、易扩展的博客解决方案。

📚 相关文档

想要深入了解 Lumos 的更多功能和使用方法？请查看以下文档：

README 文档 - 项目完整文档
Lumos CLI 使用指南 - CLI 命令的详细使用方法
Lumos 二次开发教程 - 插件和主题开发的详细教程

🎯 项目概述

核心价值

Lumos 旨在为开发者提供一个高性能、易用且可扩展的静态博客解决方案：

🚀 极致性能: 基于 Bun 运行时，冷启动时间 < 100ms
⚛️ 现代化技术栈: TypeScript + React + JSX，提供优秀的开发体验
🔧 易扩展性: 插件系统和主题系统，轻松定制功能和外观
📱 响应式设计: 移动端友好的界面设计

适用场景

👨‍💻 个人技术博客: 适合需要高性能博客系统的内容创作者
📚 技术文档: 项目文档、API 文档的理想选择
🏢 企业网站: 公司官网、产品介绍等静态网站
🌟 开源项目: 需要项目文档和展示的开源项目

🚀 核心特性

极速性能

Bun 运行时: 基于 Bun 的极速启动，冷启动时间 < 100ms
智能缓存: 基于 MD5 的文件缓存机制，只对变更文件重新解析
SSR 渲染: 服务端渲染，SEO 友好，首屏加载速度快

现代化技术栈

TypeScript: 完整的类型安全，提供优秀的开发体验
React + JSX: 使用 React 组件替代传统模板引擎，更灵活易维护
Tailwind CSS: 内置现代化 CSS 框架，响应式设计
FileSystemRouter: 基于 Bun 的自动路由系统

开发体验

热更新: 文件变化自动重新生成，支持监听模式
CLI 工具: 完整的命令行工具链，支持创建、构建、服务等功能
零配置: 开箱即用，一键启动开发环境

扩展能力

🔌 插件系统: 基于生命周期钩子的可扩展插件架构
🎨 主题系统: 支持自定义主题和组件的灵活主题机制

🏗️ 项目架构

核心组件

1. 数据生成器 (DataGenerator)

// src/generator.ts
export class DataGenerator {
  // 解析 Markdown 文件
  // 提取分类和标签
  // 生成关联关系
  // 构建完整的数据结构
}

功能特性:

📄 解析 Markdown、JSON、YAML 文件
🏷️ 自动提取文章分类和标签
🔗 生成文章-分类、文章-标签关联关系
👥 支持多作者系统
⚡ 智能缓存机制

2. 文件解析器 (Parser)

// src/parser.ts
export class Parser {
  // 解析 Markdown 文件
  // 支持 Front Matter
  // 代码高亮和 TOC 生成
  // 缓存机制
}

解析能力:

📝 Markdown 文件解析（支持 Front Matter）
🎨 代码高亮（Highlight.js）
📋 自动生成 TOC 目录
📄 摘要自动提取
📊 字数统计和阅读时间计算
🔤 中文 URL 转拼音

3. HTTP 服务器 (LumosServer)

// src/server.ts
export class LumosServer {
  // 基于 Bun FileSystemRouter
  // SSR 服务端渲染
  // 静态资源服务
  // API 接口
}

服务特性:

🛣️ 基于 Bun FileSystemRouter 的自动路由
⚡ SSR 服务端渲染
📁 静态资源管理和服务
🔌 RESTful API 接口
🔥 热更新支持

4. 布局组件 (Layout)

// src/components/Layout.tsx
export const Layout: React.FC<{
  title: string
  children: React.ReactNode
  data: DatabaseSchema
}> = ({ title, children, data }) => {
  // 响应式布局
  // 主题切换
  // SEO 优化
}

UI 特性:

📱 响应式设计，移动端友好
🌓 深色/浅色主题切换
🔍 SEO 优化（meta 标签、结构化数据）
🔎 搜索功能
✨ 现代化 UI 设计

5. Bundler HTML 系统

Bundler HTML 系统使用 Bun 的 HTML bundling 功能创建高性能页面，优先级高于主题路由。

// bundler/html/app.tsx
export default function App() {
  // React 组件
  // 高性能页面
  // 独立于主题系统
}

系统特性:

⚡ 高优先级页面处理
📦 独立的构建系统
🚀 更快的页面加载速度
🔧 灵活的页面创建方式

插件系统架构

Lumos 提供了强大的插件系统，允许开发者通过插件扩展博客的功能。插件系统基于生命周期钩子，可以在博客生成和运行的不同阶段执行自定义逻辑。

核心概念

生命周期钩子: 插件可以在特定的生命周期阶段执行代码
配置管理: 插件可以通过配置文件进行配置
易于扩展: 插件可以轻松地添加新功能

生命周期钩子

插件支持以下生命周期钩子：

onGenerateStart(generator): 数据生成开始前调用
onGenerateEnd(data): 数据生成结束后调用
onParseFile(filePath, content, type): 解析文件时调用
onRender(html, data): 渲染页面时调用
onServerStart(server): 服务器启动时调用

插件配置

插件配置在项目根目录的 lumos.config.json 文件中：

{
  "plugins": {
    "example-plugin": {
      "enabled": true,
      "options": {
        "customOption": "value"
      }
    }
  }
}

创建插件

插件是一个导出默认对象的 TypeScript 文件，放置在 plugins/ 目录中：

// plugins/example-plugin.ts
import { Plugin } from '../src/types.ts'

const examplePlugin: Plugin = {
  name: 'example-plugin',
  version: '1.0.0',
  description: '示例插件',

  async onGenerateStart(generator: any) {
    console.log('生成开始')
  },

  async onGenerateEnd(data: any) {
    console.log('生成结束')
    return data
  },

  async onParseFile(filePath: string, content: string, type: 'post' | 'page' | 'author') {
    console.log(`解析文件: ${filePath}`)
    return content
  },

  async onRender(html: string, data: any) {
    console.log('渲染页面')
    return html
  },

  async onServerStart(server: any) {
    console.log('服务器启动')
  }
}

export default examplePlugin

如需了解更多插件开发的详细信息，请参阅 Lumos 二次开发教程。

主题系统架构

Lumos 支持灵活的主题系统，允许开发者创建和使用自定义主题来改变博客的外观和功能。

主题结构

主题文件位于 themes/ 目录中，每个主题都有自己的目录：

themes/
└── default/              # 主题目录
    ├── assets/           # 主题静态资源
    │   ├── styles/       # 样式文件
    │   └── images/       # 图片资源
    ├── components/       # 主题组件
    │   └── Layout.tsx    # 布局组件
    └── routes/           # 主题路由
        ├── index.tsx     # 首页
        ├── posts.tsx     # 文章列表页
        └── post/[url].tsx # 文章详情页

主题配置

主题配置在 lumos.config.json 文件中：

{
  "theme": "default"
}

创建主题

创建新主题只需在 themes/ 目录中创建新文件夹，并按照主题结构添加文件。

1. 创建主题目录结构

mkdir -p themes/my-theme/{assets,components,routes}

2. 创建布局组件

// themes/my-theme/components/Layout.tsx
import * as React from 'react'

interface LayoutProps {
  title: string
  children: React.ReactNode
}

export const Layout: React.FC<LayoutProps> = ({ title, children }) => {
  return (
    <html>
      <head>
        <title>{title}</title>
        <link rel="stylesheet" href="/assets/styles/theme.css" />
      </head>
      <body>
        <header>
          <h1>我的自定义主题</h1>
        </header>
        <main>{children}</main>
        <footer>
          <p>&copy; 2024 我的博客</p>
        </footer>
      </body>
    </html>
  )
}

3. 创建路由页面

// themes/my-theme/routes/index.tsx
import * as React from 'react'
import { renderToString } from 'react-dom/server'
import { Layout } from '../components/Layout.tsx'

const HomePage: React.FC = () => (
  <div>
    <h2>欢迎来到我的博客</h2>
    <p>这是使用自定义主题的首页</p>
  </div>
)

export default async function handler(_request: Request): Promise<Response> {
  const html = '<!DOCTYPE html>' + renderToString(React.createElement(HomePage))
  return new Response(html, {
    headers: { 'Content-Type': 'text/html; charset=utf-8' }
  })
}

4. 配置主题

在 lumos.config.json 中切换到新主题：

{
  "theme": "my-theme"
}

主题继承

主题支持继承机制，可以通过扩展默认主题来创建自定义主题，只需覆盖需要修改的部分。

如需了解更多主题开发的详细信息，请参阅 Lumos 二次开发教程。

路由系统

前台页面路由

核心页面: / (首页), /posts (文章列表), /archives (归档), /about (关于), /links (友链)
内容页面: /post/:alias (文章详情), /page/:alias (页面详情)
分类标签: /category/:name, /tag/:name (分类/标签页面)
特殊页面: /404, /error (错误页面)
数据接口: /rss.xml, /sitemap.xml, /api/* (API 接口)

动态路由特性

🏷️ 支持别名系统 (alias)
🔤 中文 URL 自动转拼音
🔍 SEO 友好的 URL 结构
🚫 智能 404 处理

数据结构

核心实体

interface DatabaseSchema {
  posts: POST[] // 文章列表
  pages: PAGE[] // 页面列表
  authors: AUTHOR[] // 作者列表
  categories: CATEGORY[] // 分类列表
  tags: TAG[] // 标签列表
  postCategories: POST_CATEGORY[] // 文章-分类关联
  postTags: POST_TAG[] // 文章-标签关联
  [key: string]: unknown // 其他配置数据
}

文章结构

interface POST {
  id: string // 唯一标识
  title: string // 标题
  alias?: string // 别名（用于 URL）
  content: string // HTML 内容
  mdContent: string // 原始 Markdown
  excerpt: string // 摘要
  date: string // 发布日期
  published: boolean // 是否发布
  featured: boolean // 是否置顶
  author?: string // 作者
  categories: string[] // 分类
  tags: string[] // 标签
  wordCount: number // 字数统计
  readingTime: number // 阅读时间
  toc?: any[] // 目录结构
  url: string // 友好 URL
  createdAt: string // 创建时间
  updatedAt: string // 更新时间
}

📦 Bundler HTML 页面 (高优先级)

Lumos 支持使用 Bun 的 HTML bundling 功能创建页面，这种方式的优先级比主题中的 route 更高。这对于需要更高性能或特殊功能的页面非常有用。

工作原理

在 bundler/html/ 目录中创建 HTML 文件和相关的 TypeScript/JSX 组件
运行 bun run build:html 命令构建这些页面
构建后的页面会被放置在 bundler/dist/ 目录中
服务器会优先检查请求的路径是否在 bundler/dist/ 目录中存在对应文件
如果存在，则直接返回该文件，不会经过主题路由处理

优先级说明

Bundler HTML 页面具有比主题路由更高的优先级。当用户访问一个 URL 时，服务器会按照以下顺序处理：

首先检查是否是静态资源（/assets/*）
然后检查是否在 bundler/dist/ 目录中存在对应的文件
最后才检查主题路由（themes/*/routes/）

这意味着如果在 bundler/dist/ 中有一个 about.html 文件，它会优先于 themes/default/routes/about.tsx 被访问。

使用场景

创建高性能的静态页面
构建独立的 landing pages
实现特殊的前端交互效果
创建演示页面或测试页面
需要绕过主题系统的特殊页面

🛠️ 技术栈详解

运行时环境

🚀 Bun: 现代化的 JavaScript 运行时，提供极速的启动和构建性能
🔒 TypeScript: 类型安全的 JavaScript 超集，提供完整的类型系统

前端技术

⚛️ React 18: 现代化的 UI 库，支持 SSR
🔧 JSX: 在 TypeScript 中直接编写 React 组件
🎨 Tailwind CSS: 实用优先的 CSS 框架
📱 响应式设计: 移动端优先的设计理念

构建工具

🛠️ Bun 内置构建器: 无需额外配置的构建系统
🎨 PostCSS: CSS 后处理器，支持 Tailwind CSS
🔍 ESLint + Prettier: 代码质量和格式化工具

内容处理

📝 Marked: Markdown 解析器
📄 Gray Matter: Front Matter 解析
🎨 Highlight.js: 代码语法高亮
🔤 Pinyin: 中文转拼音工具

数据存储

📄 JSON: 轻量级数据存储格式
📁 文件系统: 基于文件的内容管理
⚡ 缓存系统: MD5 哈希缓存机制

🚀 使用场景

个人博客

📝 技术博客、生活记录
👥 支持多作者协作
🏷️ 完整的分类标签系统
🔍 SEO 优化，搜索引擎友好

技术文档

📚 项目文档、API 文档
🎨 支持代码高亮和目录生成
📱 响应式设计，移动端友好
📡 支持 RSS 订阅

企业网站

🏢 公司官网、产品介绍
📢 新闻发布、公告系统
📄 多页面支持
⚡ 高性能，适合低配置服务器

🔧 开发工作流

1. 内容创建

# 创建新文章
lumos new post "我的第一篇文章"

# 创建新页面
lumos new page "关于我们"

# 创建新作者
lumos new author "张三"

关于 CLI 命令的详细使用方法，请参阅 Lumos CLI 使用指南。

2. 开发调试

# 启动开发服务器（热更新）
bun run dev

# 或手动步骤
lumos gen && lumos server -w

3. 构建部署

# 完整构建
lumos build

# 生成数据文件
lumos gen

📊 性能优势

启动性能

冷启动: < 100ms（相比 Node.js 提升 3-5 倍）
热重载: 文件变化检测 < 50ms
内存占用: 相比传统方案减少 30-50%

构建性能

增量构建: 只处理变更文件
并行处理: 多文件并行解析
智能缓存: 避免重复计算

运行时性能

SSR 渲染: 首屏加载速度快
静态资源: CDN 友好的资源管理
SEO 优化: 搜索引擎友好

🌟 项目亮点

1. 现代化架构

🚀 基于 Bun 的下一代运行时
🔒 TypeScript 全覆盖，类型安全
⚛️ React + JSX 的组件化开发
🔧 函数式编程范式

2. 开发体验

⚡ 零配置启动
🔥 热更新开发
🛠️ 完整的 CLI 工具链
💡 丰富的错误提示

3. 性能优化

🧠 智能缓存机制
⚡ 增量构建
📦 资源压缩和优化
📱 响应式设计

4. 扩展性

🔌 插件化架构
🎨 主题系统支持
🧩 自定义组件
🔗 API 接口扩展

🎯 适用人群

👨‍💻 前端开发者: 熟悉 React/TypeScript 的开发者
✍️ 博客作者: 需要高性能博客系统的内容创作者
👥 技术团队: 需要技术文档和博客的企业团队
🌟 开源项目: 需要项目文档和展示的开源项目

🔮 未来规划

🎨 多主题系统支持
🖼️ 图片优化和懒加载
🔍 全文搜索功能
📱 PWA 支持
🌍 多语言国际化
💬 评论系统集成
📊 性能监控和分析
🐳 Docker 容器化支持

Lumos 致力于为开发者提供最现代化的静态博客解决方案，通过 Bun 运行时和 React 技术栈，实现极致的性能和开发体验。