Astro Theme Reimu 使用指南

2026-01-17

简介

Astro Theme Reimu 是一款博丽灵梦风格的 Astro 主题，本主题是 hexo-theme-reimu 的 Astro 移植版本。

提示

本主题同时提供了 Hexo、Hugo 和 Astro 三个版本，你可以根据自己的需求选择使用。

主要特性

基础功能

✨ 完整的博客功能
📱 响应式布局
🌙 暗黑模式支持
🌍 多语言支持（i18n）

代码与数学

🖥️ 代码高亮（基于 Expressive Code）
➗ KaTeX 数学公式支持
📊 Mermaid 流程图支持

搜索与评论

🔍 本地搜索（基于 Fuse.js）
💬 多评论系统支持：
- Valine
- Waline
- Twikoo
- Gitalk
- Giscus
- Disqus
- Utterances

统计与分析

📊 文章阅读统计（Waline/Valine）
👥 访客统计（不蒜子）
📈 网站分析：
- 百度统计
- Google Analytics
- Clarity

媒体与交互功能

🖼️ 图片懒加载
🖼️ 图片灯箱
⚡ 加载动画
🎨 AOS 滚动动画
🎯 鼠标特效

导航与结构

📑 目录导航
📰 RSS 订阅

设计与自定义

🎨 图标支持（FontAwesome、Iconify）
🔗 内置 mdx 组件
©️ 文章版权声明
🌐 响应式头图（srcset）
🎨 分享卡片功能

快速开始

安装

1
# 克隆仓库
2
git clone https://github.com/D-Sketon/astro-theme-reimu.git
3
cd astro-theme-reimu
4

5
# 安装依赖（推荐使用 pnpm）
6
pnpm install
7

8
# 启动开发服务器
9
pnpm run dev
10

11
# 构建生产版本
12
pnpm run build
13

14
# 预览构建结果
15
pnpm run preview

项目结构

1
/
2
├── public/              # 静态资源
3
│   ├── images/
4
│   │   ├── banner.webp
5
│   │   ├── banner-800w.webp
6
│   │   ├── banner-600w.webp
7
│   │   ├── favicon.ico
8
│   │   ├── reimu.png
9
│   │   └── taichi.png
10
│   └── robots.txt
11
├── src/
12
│   ├── components/      # Astro/React 组件
13
│   ├── content/         # 内容集合
14
│   │   ├── blog/        # 博客文章
15
│   │   └── config.ts    # 内容集合配置
16
│   ├── hooks/           # React Hooks
17
│   ├── languages/       # i18n 语言文件
18
│   │   ├── en.ts
19
│   │   ├── zh-cn.ts
20
│   │   ├── zh-tw.ts
21
│   │   └── ja.ts
22
│   ├── layouts/         # 页面布局
23
│   ├── pages/           # 页面路由
24
│   │   ├── about.mdx    # 关于页面
25
│   │   ├── archives/    # 归档页面
26
│   │   ├── blog/        # 博客页面
27
│   │   ├── categories/  # 分类页面
28
│   │   ├── tags/        # 标签页面
29
│   │   └── rss.xml.js   # RSS 订阅
30
│   ├── plugins/         # Markdown 插件
31
│   ├── styles/          # 样式文件
32
│   ├── utils/           # 工具函数
33
│   ├── config.ts        # 主题配置文件
34
│   ├── covers.ts        # 封面图配置
35
│   └── env.d.ts
36
├── astro.config.mjs     # Astro 配置
37
├── package.json
38
└── tsconfig.json

TIP

所有博客文章都存储在 src/content/blog 目录中，关于页面存储在 src/pages 目录中。任何静态资产（如图像）都可以放置在 public/ 目录中。

主题配置

主题的所有配置都在 src/config.ts 文件中进行。

基本配置

站点信息

1
export default {
2
  site: {
3
    title: "My Blog", // 站点标题
4
    subtitle: "My Blog Subtitle", // 站点副标题
5
    description: "Your blog description", // 站点描述
6
    keywords: "blog, astro, theme", // 关键词
7
    author: "Your Name", // 作者名称
8
    language: "zh-CN", // 站点语言 (en | zh-CN | zh-TW | ja)
9
  },
10
};

侧边栏配置

1
export default {
2
  sidebar: {
3
    avatar: "/images/avatar.webp", // 头像路径（相对于 public 目录）
4
    position: "right", // 侧边栏位置 (left | right)
5
  },
6
};

侧边栏小部件

1
export default {
2
  widgets: [
3
    "category", // 分类
4
    "tag", // 标签
5
    "tagcloud", // 标签云
6
    "archive", // 归档
7
    "recent_posts", // 最近文章
8
  ],
9
};

菜单导航

1
export default {
2
  menu: [
3
    { name: "home", url: "/" }, // 菜单项名称（对应 i18n 翻译）
4
    { name: "archives", url: "/archives" },
5
    { name: "about", url: "/about" },
6
  ],
7
};

头图与封面配置

头图配置

1
export default {
2
  banner: "/images/banner.webp", // 头图路径
3

4
  // 响应式头图（可选）
5
  banner_srcset: {
6
    enable: true,
7
    srcset: [
8
      { src: "/images/banner-600w.webp", media: "(max-width: 479px)" },
9
      { src: "/images/banner-800w.webp", media: "(max-width: 799px)" },
10
      { src: "/images/banner.webp", media: "(min-width: 800px)" },
11
    ],
12
  },
13
};

封面配置

在 src/covers.ts 中配置随机封面图列表：

1
export default [
2
  "https://example.com/cover1.webp",
3
  "https://example.com/cover2.webp",
4
  "https://example.com/cover3.webp",
5
];

INFO

文章封面显示逻辑：

如果文章 Front Matter 中指定了 cover，则使用指定的封面

否则从 covers.ts 中随机选择一张

如果 covers.ts 为空，则使用头图作为封面

页脚配置

1
export default {
2
  footer: {
3
    since: 2020, // 起始年份（会显示为 2020 - 当前年份）
4
    powered: true, // 是否显示 "Powered by Astro"
5
    count: true, // 是否显示文章统计
6
    busuanzi: true, // 是否启用不蒜子访客统计
7
    icp: {
8
      icpnumber: "", // ICP备案号
9
      beian: "", // 网安备案号
10
      recordcode: "", // 网安备案链接中的recordcode参数
11
    },
12
    moe_icp: {
13
      icpnumber: "", // 萌国ICP备案号
14
    },
15
  },
16
};

社交链接

1
export default {
2
  social: {
3
    email: "mailto:your@email.com",
4
    github: "https://github.com/yourname",
5
    twitter: "https://twitter.com/yourname",
6
    facebook: "https://www.facebook.com/yourname",
7
    // 更多社交平台...
8
  },
9
};

评论系统配置

主题支持多种评论系统，你可以根据需求选择其中一种。

Waline 是一个简洁、安全的评论系统。

1
export default {
2
  waline: {
3
    enable: true,
4
    serverURL: "your-server-url", // Waline 服务器地址
5
    lang: "zh-CN", // 语言
6
    locale: {}, // 自定义语言包
7
    emoji: [
8
      // 表情包
9
      "https://unpkg.com/@waline/emojis@1.2.0/weibo",
10
      "https://unpkg.com/@waline/emojis@1.2.0/bilibili",
11
    ],
12
    meta: ["nick", "mail", "link"], // 评论者信息
13
    requiredMeta: ["nick", "mail"], // 必填项
14
    wordLimit: 0, // 评论字数限制（0 为不限制）
15
    pageSize: 10, // 每页评论数
16
    pageview: true, // 是否启用浏览量统计
17
  },
18
};

Valine 是一个基于 LeanCloud 的快速、简洁且高效的无后端评论系统。

1
export default {
2
  valine: {
3
    enable: true,
4
    appId: "your-app-id", // LeanCloud App ID
5
    appKey: "your-app-key", // LeanCloud App Key
6
    pageSize: 10, // 评论列表分页
7
    avatar: "mp", // Gravatar 头像风格
8
    lang: "zh-cn", // 语言
9
    placeholder: "Just go go", // 评论框占位文本
10
    guest_info: "nick,mail,link", // 评论者信息字段
11
    recordIP: true, // 是否记录评论者 IP
12
    highlight: true, // 是否高亮代码块
13
    visitor: false, // 是否显示访问量
14
    serverURLs: "", // LeanCloud 服务器地址（可选）
15
  },
16
};

Gitalk 是一个基于 GitHub Issue 和 Preact 的现代评论组件。

1
export default {
2
  gitalk: {
3
    enable: true,
4
    clientID: "your-client-id", // GitHub Application Client ID
5
    clientSecret: "your-client-secret", // GitHub Application Client Secret
6
    repo: "your-repo", // 存储评论的 GitHub 仓库
7
    owner: "your-name", // 仓库所有者
8
    admin: ["your-name"], // 仓库管理员（可以是数组）
9
  },
10
};

Giscus 是一个基于 GitHub Discussion 的评论系统。

1
export default {
2
  giscus: {
3
    enable: true,
4
    repo: "your-username/your-repo", // GitHub 仓库
5
    repoId: "your-repo-id", // 仓库 ID
6
    category: "your-category", // 分类名称
7
    categoryId: "your-category-id", // 分类 ID
8
    mapping: "pathname", // 评论映射方式
9
    strict: 0, // 严格模式
10
    reactionsEnabled: 1, // 启用反应
11
    emitMetadata: 0, // 发出元数据
12
    inputPosition: "bottom", // 输入框位置
13
  },
14
};

Twikoo 支持多种部署方式的评论系统。

1
export default {
2
  twikoo: {
3
    enable: true,
4
    envId: "your-env-id", // 腾讯云环境填 envId；Vercel 环境填地址
5
    region: "", // 腾讯云区域（可选）
6
  },
7
};

Utterances

Utterances 是一个基于 GitHub Issue 的轻量级评论组件。

1
export default {
2
  utterances: {
3
    enable: true,
4
    repo: "owner/repo", // GitHub 仓库
5
    issue_term: "title", // Issue 映射方式
6
    theme: "github-light", // 主题
7
  },
8
};

Disqus

Disqus 是一个全球性的评论系统。

1
export default {
2
  disqus: {
3
    enable: true,
4
    shortname: "your-shortname", // Disqus shortname
5
    count: true, // 是否启用评论数量统计
6
  },
7
};

统计分析配置

网站分析

1
export default {
2
  analytics: {
3
    baidu_analytics: "your-baidu-id", // 百度统计 ID
4
    google_analytics: "your-ga-id", // Google Analytics ID
5
    clarity: "your-clarity-id", // Microsoft Clarity ID
6
  },
7
};

其他功能配置

版权声明

1
export default {
2
  copyright: {
3
    enable: true, // 是否启用版权声明
4
    content: {
5
      author: true, // 显示作者
6
      link: true, // 显示文章链接
7
      title: true, // 显示文章标题
8
      date: false, // 显示发布日期
9
      updated: false, // 显示更新日期
10
      license: true, // 显示许可协议
11
      license_type: "by-nc-sa", // 许可协议类型
12
    },
13
  },
14
};

加载动画

1
export default {
2
  preloader: {
3
    enable: true, // 是否启用加载动画
4
    text: "少女祈祷中...", // 加载文本
5
    rotate: true, // 图标是否旋转
6
  },
7
};

友链配置

1
export default {
2
  friend: [
3
    {
4
      name: "Friend Name", // 友链名称
5
      url: "https://friend.com", // 友链地址
6
      desc: "Description", // 友链描述
7
      avatar: "/avatar.webp", // 友链头像
8
    },
9
  ],
10
};

首页分类卡片

1
export default {
2
  home_categories: {
3
    enable: true, // 是否启用首页分类卡片
4
    content: [
5
      {
6
        categories: "Blog", // 分类名称
7
        cover: "/images/category-cover.webp", // 分类封面（可选）
8
      },
9
    ],
10
  },
11
};

分享功能

1
export default {
2
  share: [
3
    "weibo", // 微博
4
    "qq", // QQ
5
    "weixin", // 微信
6
    // "twitter",  // Twitter
7
    // "facebook", // Facebook
8
    // "linkedin", // LinkedIn
9
    // "reddit",   // Reddit
10
  ],
11
};

赞助功能

1
export default {
2
  sponsor: {
3
    enable: false, // 是否启用赞助功能
4
    qr: [
5
      { name: "支付宝", src: "/sponsor/alipay.jpg" },
6
      { name: "微信", src: "/sponsor/wechat.png" },
7
    ],
8
  },
9
};

文章过期提醒

1
export default {
2
  outdate: {
3
    enable: false, // 是否启用文章过期提醒
4
    daysAgo: 180, // 多少天前的文章算过期
5
  },
6
};

鼠标特效

1
export default {
2
  firework: {
3
    enable: true, // 是否启用鼠标特效
4
    disable_on_mobile: false, // 是否在移动端禁用
5
    options: {
6
      // 详细配置请参考 mouse-firework 文档
7
    },
8
  },
9
};

三角徽标

1
export default {
2
  triangle_badge: {
3
    enable: false,
4
    type: "github", // 图标类型
5
    link: "https://github.com/yourname",
6
  },
7
};

写作指南

创建文章

在 src/content/blog/ 目录下创建 .md 或 .mdx 文件：

1
---
2
title: 你的文章标题
3
description: 文章描述
4
pubDate: 2024-01-01
5
updatedDate: 2024-01-02
6
cover: https://example.com/cover.jpg
7
tags:
8
  - tag1
9
  - tag2
10
categories:
11
  - category1
12
---
13

14
你的文章内容...

Front Matter 字段说明

字段	描述	类型	必填	默认值
title	文章标题	`string`	是	-
description	文章描述（用于 SEO）	`string`	是	-
keywords	文章关键词（用于 SEO）	`string[] \| string`	否	`[]`
pubDate	发布日期	`Date`	是	-
updatedDate	更新日期	`Date`	否	-
cover	封面图 URL	`string`	否	-
tags	标签列表	`string[]`	否	`[]`
categories	分类列表	`string[]`	否	`[]`
excerpt	文章摘要	`string`	否	-
comment	是否启用评论系统	`boolean`	否	`true`
author	文章作者	`string`	否	-
toc	是否显示目录	`boolean`	否	`true`
sponsor	是否显示赞助信息	`boolean`	否	-
copyright	是否显示版权声明	`boolean`	否	-
share	是否显示分享按钮	`boolean`	否	-
outdated	文章是否过期	`boolean`	否	`false`

数学公式

主题内置了 KaTeX 支持，可以直接在 Markdown 中使用 LaTeX 语法。

行内公式：

1
行内公式：$E = mc^2$

效果： $E = mc^2$

块级公式：

1
$$
2
\frac{n!}{k!(n-k)!} = \binom{n}{k}
3
$$

效果：

\frac{n!}{k!(n-k)!} = \binom{n}{k}

Mermaid 流程图

主题内置了 Mermaid 支持，可以绘制流程图、时序图等。

1
```mermaid
2
graph TD
3
    A[开始] --> B[处理]
4
    B --> C{判断}
5
    C -->|是| D[结束]
6
    C -->|否| B
7
```

代码块

代码块基于 Expressive Code 实现，支持：

语法高亮
行号显示
代码折叠（使用 collapse 标记）
代码复制按钮

基本代码块：

1
```javascript
2
function hello() {
3
  console.log("Hello, World!");
4
}
5
```

代码折叠：

1
```js collapse={1-5, 12-14}
2
// 这些行默认折叠
3
function example() {
4
  console.log("Hello");
5
}
6

7
// 这些行默认展开
8
const result = example();
9
```

内置组件

主题提供了丰富的内置 MDX 组件，以下是一些常用组件的使用方法。

链接组件

内部链接

用于在文章中创建指向其他文章的精美链接卡片，支持显示封面图和摘要。适合在文章中推荐相关内容或创建内容导航。

1
<Link slug="post-slug" title="文章标题" cover="封面URL" />

Props:

slug (string, 可选): 文章 slug
url (string, 可选): 外部链接 URL
title (string, 可选): 链接标题
cover (string | "auto", 可选): 封面图片

外部链接

用于创建指向外部网站的精美链接卡片，自动识别为外部链接。适合在文章中分享外部资源或推荐其他网站。

1
<Link url="https://github.com" title="GitHub" cover="auto" />

内容组件

友情链接卡片

展示友情链接列表，每个链接包含头像、名称和描述。适合在关于页面或专门的友链页面展示合作伙伴网站。

友情链接卡片使用全局配置中的友链列表：

1
<FriendCard />

Props: 无

热力图卡片

基于访问量数据生成热力图可视化，展示内容活跃度。适合在个人主页或数据统计页面展示访问数据。

1
<HeatMapCard levelStandard="1000,5000,10000" />

Props:

levelStandard (string, 可选): 等级标准，默认 “1000,5000,10000”

标签轮盘

以轮盘形式展示标签列表，用户可以点击随机选择标签。适合在标签页面或侧边栏增加趣味性交互。

1
<TagRoulette tags="标签1,标签2,标签3" icon="🎯" />

Props:

tags (string, 可选): 标签列表，用逗号分隔，默认预设标签
icon (string, 可选): 按钮图标，默认 “🕹️”

布局组件

标签页

创建多标签页界面，可以在同一区域展示不同内容。适合展示相关内容的多个方面或选项卡式导航。

1
<Tabs active={1} center={false}>
2
  <TabItem title="Tab 1">内容1</TabItem>
3
  <TabItem title="Tab 2">内容2</TabItem>
4
</Tabs>

Tabs Props:

active (number, 可选): 默认激活的标签页，默认 1
center (boolean, 可选): 是否居中，默认 false

TabItem Props:

title (string, 必需): 标签页标题

折叠详情

创建可展开/折叠的内容区域，可以隐藏次要信息。适合展示详细说明、代码示例或长文本内容。

1
<Details summary="点击展开">
2
  这里是折叠的内容
3
</Details>

Props:

summary (string, 必需): 折叠标题

网格布局

创建响应式网格布局，可以灵活排列内容。适合展示卡片列表、图片网格或等宽内容块。

1
<Grid col={3}>
2
  <GridCell>单元格1</GridCell>
3
  <GridCell>单元格2</GridCell>
4
  <GridCell>单元格3</GridCell>
5
</Grid>

Grid Props:

width (number, 可选): 最小宽度，默认 240
col (number, 可选): 列数，优先于 width

GridCell Props: 无

照片墙

创建精美的图片展示墙，支持灯箱效果。适合在文章中展示多张图片或创建图片集页面。

1
<Gallery>
2
  ![图片1](image1.jpg)
3
  ![图片2](image2.jpg)
4
</Gallery>

Props: 无

警告块

创建不同类型的提示信息框，支持多种样式。适合突出重要信息、警告或提示用户注意。

1
<AlertBlockquote type="info" title="提示">
2
  这是一个信息提示
3
</AlertBlockquote>
4

5
<AlertBlockquote type="warning">
6
  这是一个警告提示
7
</AlertBlockquote>
8

9
<AlertBlockquote type="danger">
10
  这是一个危险提示
11
</AlertBlockquote>

Props:

type ("info" | "warning" | "danger" | "tip" | "important", 可选): 警告类型，默认 “info”
title (string, 可选): 自定义标题，默认使用 type 大写

部署

配置站点信息

编辑 astro.config.mjs：

1
export default defineConfig({
2
  site: "https://yourusername.github.io", // 你的站点 URL
3
  base: "your-repo-name", // 子路径（如部署到 GitHub Pages）
4
  // ...
5
});

GitHub Pages

构建项目：

1
pnpm run build

将 dist/ 目录部署到 GitHub Pages

或者配置 GitHub Actions 自动部署（推荐），具体可参考 Github Pages。

Vercel / Netlify

这些平台会自动识别 Astro 项目：

连接 GitHub 仓库
平台会自动检测并使用正确的构建命令
点击部署即可

具体请参考 Netlify 或 Vercel 文档。

开发进阶

添加新页面

在 src/pages/ 目录下创建文件即可，Astro 会自动处理路由。

修改样式

样式文件位于 src/styles/ 目录：

base.stylus - 基础样式
global.css - 全局样式
markdown.stylus - Markdown 渲染样式

多语言支持（i18n）

语言文件位于 src/languages/ 目录，支持的语言：

en.ts - English
zh-cn.ts - 简体中文
zh-tw.ts - 繁体中文
ja.ts - 日本語

要添加新语言，创建对应的 .ts 文件并参考现有文件的结构。

总结

Astro Theme Reimu 是一个功能丰富、高度可定制的博客主题。通过本指南，你应该能够快速上手并根据自己的需求进行配置。如果在使用过程中遇到问题，欢迎到 GitHub Issues 提问。

TIP

更多详细信息和最新更新，请访问 GitHub 仓库。