1399 words
|
23.32 分钟
Lumos CLI USAGE 教程
2025-09-03
开发教程
/
技术文档

Lumos CLI 使用指南

Lumos CLI 是一个基于 Bun 运行时的静态博客生成器命令行工具。您可以使用两种方式来运行Lumos命令：

  1. 使用 lumos 命令（需要将Lumos添加到系统PATH）
  2. 使用 bun run 命令（推荐方式）

如果您想了解 Lumos 的更多高级功能，如插件系统和主题系统，请参阅 Lumos 项目介绍 和 Lumos 二次开发教程。

📚 相关文档

📋 安装

确保已安装 Bun 运行时：

curl -fsSL https://bun.sh/install | bash

🚀 快速开始

工作流程示例

1. 初始化项目

# 克隆项目
git clone <repository-url>
cd lumos

# 安装依赖
bun install

2. 创建内容

使用 lumos 命令：

# 创建文章
lumos new post "Lumos 使用指南"

# 创建页面
lumos new page "关于" -p "info"

# 创建作者
lumos new author "开发者"

使用 bun run 命令：

# 创建文章
bun run src/cli.ts new post "Lumos 使用指南"

# 创建页面
bun run src/cli.ts new page "关于" -p "info"

# 创建作者
bun run src/cli.ts new author "开发者"

3. 生成数据

使用 lumos 命令：

# 生成数据文件
lumos gen

使用 bun run 命令：

# 生成数据文件
bun run src/cli.ts gen

4. 启动开发服务器

使用 lumos 命令：

# 启动服务器并监听文件变化
lumos server -w

使用 bun run 命令：

# 启动服务器并监听文件变化
bun run src/cli.ts server -w

5. 构建项目

使用 lumos 命令：

# 构建项目用于生产环境
lumos build

使用 bun run 命令：

# 构建项目用于生产环境
bun run src/cli.ts build

6. 构建 主题 CSS 文件

使用 lumos 命令：

# 构建 CSS 文件
lumos css

# 监听 CSS 文件变化
lumos css -w

使用 bun run 命令：

# 构建 CSS 文件
bun run src/cli.ts css

# 监听 CSS 文件变化
bun run src/cli.ts css -w

🛠️ 命令详解

CLI命令模块化规范

Lumos 采用了现代化的 CLI 命令模块化设计，每个命令都被独立实现并放置在 src/commands 目录中，cli.ts 文件仅负责参数解析和命令路由。这种设计使得命令实现更加清晰、易于维护和扩展。

命令结构

  • src/commands/gen.ts - 数据生成命令
  • src/commands/server.ts - 服务器启动命令
  • src/commands/build.ts - 项目构建命令
  • src/commands/assets.ts - 资源处理命令
  • src/commands/build-css.ts - CSS 构建命令
  • src/commands/new.ts - 内容创建命令
  • src/commands/webp.ts - WebP 图片转换命令
  • src/commands/help.ts - 帮助命令
  • src/commands/version.ts - 版本查看命令

这种模块化的设计使得每个命令的实现逻辑相互独立，便于维护和扩展。

new 命令

用于创建新的文章、页面或作者文件。

语法

使用 lumos 命令：

lumos new <type> <title> [options]

使用 bun run 命令：

bun run src/cli.ts new <type> <title> [options]

参数

  • <type>: 文件类型，支持 post、page、author
  • <title>: 文件标题

选项

  • -p, --path <path>: 指定子目录路径

示例

  1. 创建新文章

    使用 lumos 命令：

    lumos new post "我的第一篇文章"

    使用 bun run 命令：

    bun run src/cli.ts new post "我的第一篇文章"

  2. 在子目录中创建文章

    使用 lumos 命令：

    lumos new post "JavaScript 教程" -p "tutorials"

    使用 bun run 命令：

    bun run src/cli.ts new post "JavaScript 教程" -p "tutorials"

  3. 创建新页面

    使用 lumos 命令：

    lumos new page "关于我们"

    使用 bun run 命令：

    bun run src/cli.ts new page "关于我们"

  4. 在子目录中创建页面

    使用 lumos 命令：

    lumos new page "联系方式" -p "info"

    使用 bun run 命令：

    bun run src/cli.ts new page "联系方式" -p "info"

  5. 创建新作者

    使用 lumos 命令：

    lumos new author "张三"

    使用 bun run 命令：

    bun run src/cli.ts new author "张三"

gen 命令

用于解析所有 Markdown、JSON、YAML 文件，生成 data.json 数据文件。

语法

使用 lumos 命令：

lumos gen

使用 bun run 命令：

bun run src/cli.ts gen

示例

  1. 生成数据文件

    使用 lumos 命令：

    lumos gen

    使用 bun run 命令：

    bun run src/cli.ts gen

  2. 生成数据文件（别名命令）

    使用 lumos 命令：

    lumos generate

    使用 bun run 命令：

    bun run src/cli.ts generate

server 命令

启动开发服务器，支持监听文件变化自动重新生成。

语法

使用 lumos 命令：

lumos server [options]

使用 bun run 命令：

bun run src/cli.ts server [options]

选项

  • -p, --port <port>: 指定服务器端口（默认: 3060）
  • -w, --watch: 启用监听模式，文件变化自动重新生成

示例

  1. 启动开发服务器

    使用 lumos 命令：

    lumos server

    使用 bun run 命令：

    bun run src/cli.ts server

  2. 指定端口启动服务器

    使用 lumos 命令：

    lumos server -p 8080

    使用 bun run 命令：

    bun run src/cli.ts server -p 8080

  3. 启用监听模式

    使用 lumos 命令：

    lumos server -w

    使用 bun run 命令：

    bun run src/cli.ts server -w

  4. 指定端口并启用监听模式

    使用 lumos 命令：

    lumos server -p 8080 -w

    使用 bun run 命令：

    bun run src/cli.ts server -p 8080 -w

build 命令

构建项目，包括生成数据文件和处理资源文件。

语法

使用 lumos 命令：

lumos build

使用 bun run 命令：

bun run src/cli.ts build

示例

  1. 构建项目

    使用 lumos 命令：

    lumos build

    使用 bun run 命令：

    bun run src/cli.ts build

assets 命令

处理资源文件，确保资源目录存在并创建必要的子目录。

语法

使用 lumos 命令：

lumos assets

使用 bun run 命令：

bun run src/cli.ts assets

示例

  1. 处理资源文件

    使用 lumos 命令：

    lumos assets

    使用 bun run 命令：

    bun run src/cli.ts assets

css 命令

构建 CSS 文件，支持监听模式。

语法

使用 lumos 命令：

lumos css [options]

使用 bun run 命令：

bun run src/cli.ts css [options]

选项

  • -w, --watch: 启用监听模式，监听 CSS 文件变化

示例

  1. 构建 主题 CSS 文件

    使用 lumos 命令：

    lumos css

    使用 bun run 命令：

    bun run src/cli.ts css

  2. 监听 主题 CSS 文件变化

    使用 lumos 命令：

    lumos css -w

    使用 bun run 命令：

    bun run src/cli.ts css -w

webp 命令

将图片转换为 WebP 格式，以减小文件体积并提升网站加载速度。

语法

使用 lumos 命令：

lumos webp <input> <output> [options]

使用 bun run 命令：

bun run src/cli.ts webp <input> <output> [options]

参数

  • <input>: 输入图片文件或目录路径
  • <output>: 输出 WebP 图片文件或目录路径

选项

  • --quality <number>: WebP 图片质量（1-100，默认: 80）
  • --effort <number>: WebP 压缩级别（0-6，默认: 6）

支持的图片格式

  • JPEG / JPG
  • PNG
  • TIFF
  • GIF
  • BMP

示例

  1. 转换单个图片

    使用 lumos 命令：

    lumos webp ./assets/images/logo.png ./assets/images-webp/logo.webp --quality=85

    使用 bun run 命令：

    bun run src/cli.ts webp ./assets/images/logo.png ./assets/images-webp/logo.webp --quality=85

  2. 批量转换目录中的所有图片

    使用 lumos 命令：

    lumos webp ./themes/default/assets/images ./themes/default/assets/images-webp --quality=80

    使用 bun run 命令：

    bun run src/cli.ts webp ./themes/default/assets/images ./themes/default/assets/images-webp --quality=80

  3. 高质量转换

    使用 lumos 命令：

    lumos webp ./images ./webp-images --quality=95 --effort=4

    使用 bun run 命令：

    bun run src/cli.ts webp ./images ./webp-images --quality=95 --effort=4

WebP 图片通常比原图小 25-35%，同时保持相近的视觉质量，有助于提升网站性能。

📁 生成的文件结构

文章 (Post)

生成路径: source/_posts/[path/]<title>.md

页面 (Page)

生成路径: source/_pages/[path/]<title>.md

作者 (Author)

生成路径: source/_authors/[path/]<title>.md

📄 模板结构

所有生成的文件都包含以下 Front Matter：

---
id: <自动生成的UUID>
title: <标题>
cover:
created_time: <创建时间>
updated_time: <更新时间>
categories:
tags:
excerpt:
published: true
---

🎨 自定义模板

模板文件位于 templates/ 目录下：

  • templates/post.tsx - 文章模板
  • templates/page.tsx - 页面模板
  • templates/author.tsx - 作者模板

你可以修改这些 TSX 文件来自定义生成的文件格式。

⚙️ 技术特性

  • ✅ 使用 JSX 模板
  • ✅ 基于 UUID v5 的稳定 ID 生成
  • ✅ 自动创建目录结构
  • ✅ 重复文件检测
  • ✅ 支持中文标题
  • ✅ 统一的时间格式
  • ✅ 支持子目录路径
  • ✅ 自动生成友好 URL
  • ✅ 中文标题自动转拼音

🔧 高级用法

使用 package.json 脚本

Lumos 项目提供了预定义的 npm 脚本：

# 启动开发环境（等同于 lumos server -w）
bun run dev

# 创建新内容
bun run new post "文章标题"

# 生成数据
bun run gen

# 构建项目
bun run build

# 构建 主题CSS 文件
bun run build:css

# 监听 主题CSS 文件变化
bun run build:css:watch

命令组合使用

使用 lumos 命令：

# 一次性生成数据并启动服务器
lumos gen && lumos server

# 构建项目并处理资源
bun run src/cli.ts build && bun run src/cli.ts assets

# 构建 主题 CSS 文件并监听变化
lumos css && lumos css -w

使用 bun run 命令：

# 一次性生成数据并启动服务器
bun run src/cli.ts gen && bun run src/cli.ts server

# 构建项目并处理资源
bun run src/cli.ts build && bun run src/cli.ts assets

# 构建 主题 CSS 文件并监听变化
bun run src/cli.ts css && bun run src/cli.ts css -w

🎯 推荐使用方式

我们推荐使用 bun run 命令，因为：

  1. 无需全局安装：不需要将Lumos添加到系统PATH
  2. 版本一致：确保使用项目中定义的Lumos版本
  3. 跨平台兼容：在不同操作系统上行为一致
  4. 易于团队协作：所有团队成员使用相同的命令方式

如果您想深入了解如何扩展 Lumos 的功能，例如创建自定义插件或主题，请参阅 Lumos 二次开发教程。

https://uuice.com/pages/lumos-cli-usage
Author
Unknown
Published at
2025-09-03
© 2025 轻盈的鱼. All Rights Reserved. /RSS/Sitemap
Powered byUUICE&LumosTheme 移植自fuwari
浙ICP备13002567号-4