博客使用指南
博客使用指南
本文档详细介绍博客的各项功能和使用方法。
目录
- 项目结构
- 命名规范
- 文章系统 (posts)
- 日常动态 (moments)
- 生活记录 (life)
- 相册 (album)
- 导航 (daohang)
- 弹幕 (danmu)
- 特殊页面 (spec)
- 番组计划 (bangumi)
- 侧边栏组件
- 评论系统
- 高级功能配置
- SEO 与统计
- 主题定制
- 部署与维护
- 常见问题
- 附录
项目结构
src/├── content/│ ├── posts/ # 博客文章│ ├── moments/ # 日常动态│ ├── album/ # 相册│ ├── daohang/ # 网站导航│ ├── danmu/ # 弹幕留言│ ├── bangumi/ # 番组计划│ ├── spec/ # 特殊页面(关于、友链等)│ └── life/ # 生活记录│ ├── ideas/ # 想法│ ├── places/ # 地点│ ├── checkin/ # 打卡│ ├── routines/ # 日常规划│ ├── health/│ │ ├── workout/ # 运动│ │ ├── sleep/ # 睡眠│ │ └── food/ # 饮食│ └── notebooks/ # 笔记本├── pages/ # 页面路由├── components/ # 组件├── config/ # 配置文件│ ├── siteConfig.ts # 站点配置│ ├── sidebarConfig.ts # 侧边栏配置│ ├── navBarConfig.ts # 导航栏配置│ ├── commentConfig.ts # 评论配置│ └── ...└── i18n/ # 国际化命名规范
为了保持博客内容的整洁有序,建议按照以下规范命名文件和文件夹。所有文件名和文件夹名建议使用中文,与各功能模块的语义相匹配。
概览
| 功能模块 | 存放路径 | 命名建议 | 示例 | 子文件夹 |
|---|---|---|---|---|
| 文章 | src/content/posts/ | 按主题分类的子文件夹 + 文章标题 | 技术/Java基础.md、生活/第一次旅行.md | ✅ 支持 |
| 日常动态 | src/content/moments/ | 日期格式 | 2026-04-20.md | ❌ 不支持 |
| 运动记录 | src/content/life/health/workout/ | 日期格式 | 2026-04-20.md | ❌ 不支持 |
| 睡眠记录 | src/content/life/health/sleep/ | 日期格式 | 2026-04-20.md | ❌ 不支持 |
| 饮食记录 | src/content/life/health/food/ | 日期格式或描述性名称 | 2026-04-20.md、健康早餐.md | ❌ 不支持 |
| 奇思妙想 | src/content/life/ideas/ | 简短描述性标题 | 晨跑计划.md、新项目想法.md | ❌ 不支持 |
| 打卡项目 | src/content/life/checkin/ | 习惯/目标名称 | 每日阅读.md、早睡早起.md、喝水提醒.md | ❌ 不支持 |
| 日常规划 | src/content/life/routines/ | 规划类型或时间 | 晨间习惯.md、晚间安排.md、周末计划.md | ❌ 不支持 |
| 去过的地方 | src/content/life/places/ | 地点名称 | 成都.md、杭州西湖.md、公司.md | ❌ 不支持 |
| 笔记本 | src/content/life/notebooks/ | 笔记本类型(文件夹) + 日期(条目) | 日记/2026-04-20.md、读书笔记/2026-04.md | ✅ 本身就是文件夹 |
| 番组计划 | src/content/bangumi/ | 按类型分子文件夹 + 作品名称 | anime/进击的巨人.md、book/人类简史.md | ✅ 支持 |
子文件夹分类说明
| 功能模块 | 是否支持子文件夹 | 说明 |
|---|---|---|
| 文章 (posts) | ✅ 支持 | 可以按主题/分类创建子文件夹,子文件夹名称即为分类 |
| 日常动态 (moments) | ❌ 不支持 | 建议扁平化管理,所有动态文件直接放在 moments/ 目录 |
| 运动记录 (workout) | ❌ 不支持 | 建议按日期命名,扁平化管理 |
| 睡眠记录 (sleep) | ❌ 不支持 | 建议按日期命名,扁平化管理 |
| 饮食记录 (food) | ❌ 不支持 | 建议按日期或简短描述命名,扁平化管理 |
| 奇思妙想 (ideas) | ❌ 不支持 | 建议扁平化管理,用标题区分不同想法 |
| 打卡项目 (checkin) | ❌ 不支持 | 每个文件代表一个打卡项目,扁平化管理 |
| 日常规划 (routines) | ❌ 不支持 | 建议扁平化管理,每个规划一个文件 |
| 去过的地方 (places) | ❌ 不支持 | 建议扁平化管理,每个地点一个文件 |
| 笔记本 (notebooks) | ✅ 本身就是文件夹 | 每个笔记本是一个文件夹,条目放在各自的文件夹内 |
| 番组计划 (bangumi) | ✅ 支持 | 建议按类型创建子文件夹:anime、book、music、game、real |
详细说明
图例说明:
- ✅ 支持子文件夹分类
- ❌ 不支持子文件夹(建议扁平化管理)
1. 文章 (posts) ✅ 支持子文件夹分类
命名建议: 子文件夹按主题/分类命名,文件名使用文章标题。
posts/├── 技术/│ ├── Java基础.md│ ├── Docker入门.md│ └── 算法笔记.md├── 生活/│ ├── 第一次旅行.md│ └── 养猫日记.md├── 英语学习/│ ├── 背单词方法.md│ └── 语法笔记.md└── 随笔/ └── 关于成长.md说明:
- 子文件夹名称代表文章分类
- 文件名使用文章的实际标题,便于识别内容
- 避免使用
1.md、a.md等无意义名称
2. 日常动态 (moments) ❌ 不支持子文件夹
命名建议: 使用日期格式 YYYY-MM-DD.md。
moments/├── 2026-04-20.md # 4月20日的动态├── 2026-04-19.md # 4月19日的动态└── 2026-04-18.md # 4月18日的动态说明:
- 每条动态对应一天的记录
- 日期格式便于按时间排序和查找
- 文件名只作为元数据,实际内容在 frontmatter 的
published字段指定- 不支持子文件夹分类,所有动态文件直接放在
moments/目录下
3. 健康记录
命名建议: 使用日期格式或简短的描述性名称。
运动记录 (workout)
workout/├── 2026-04-20.md # 4月20日的运动├── 2026-04-18.md # 4月18日的运动└── 2026-04-15.md # 4月15日的运动说明:
- 主要按日期命名,因为每天可能有多次运动记录
- 如果一天有多次不同运动,可用简短描述:
2026-04-20-晨跑.md、2026-04-20-健身房.md
睡眠记录 (sleep)
sleep/├── 2026-04-20.md # 4月20日晚的睡眠├── 2026-04-19.md # 4月19日晚的睡眠└── 2026-04-18.md # 4月18日晚的睡眠说明:
- 睡眠记录按日期命名,指当天晚上的睡眠
- 通常每天一条记录
饮食记录 (food)
food/├── 2026-04-20.md # 4月20日的饮食├── 健康早餐.md # 健康早餐记录└── 节日大餐.md # 特殊日期的饮食说明:
- 日常饮食按日期命名
- 特殊的饮食记录可用描述性名称
4. 奇思妙想 (ideas) ❌ 不支持子文件夹
命名建议: 简短描述想法内容,不要超过20个字。
ideas/├── 晨跑计划.md # 关于晨跑的想法├── 学习新语言.md # 关于学外语的想法├── 开发独立博客.md # 关于做博客的想法└── 每周一本书.md # 关于阅读的想法说明:
- 想法名称应简洁明了,概括核心内容
- 不需要包含日期,因为有
createdAt字段记录创建时间- 已完成的想法会在侧边栏显示,使用有意义的名称很重要
5. 打卡记录 (checkin) ❌ 不支持子文件夹
命名建议: 使用习惯/目标名称。
checkin/├── 每日阅读.md # 阅读打卡├── 早睡早起.md # 作息打卡├── 每日喝水.md # 喝水打卡├── 运动健身.md # 运动打卡└── 单词背诵.md # 学习打卡说明:
- 文件名就是打卡项目的名称
- 一次打卡代表一个习惯/目标
- 打卡记录保存在 frontmatter 的
checkins数组中
6. 日常规划 (routines) ❌ 不支持子文件夹
命名建议: 按时间段或规划类型命名。
routines/├── 晨间习惯.md # 早晨的例行安排├── 午休安排.md # 午休时间规划├── 晚间习惯.md # 晚上的例行安排├── 周末计划.md # 周末活动规划└── 学习计划.md # 学习时间安排说明:
- 规划代表一种例程或习惯模板
- 可以按一天中的时间段或按功能分类
- 文件名应体现规划的用途
7. 去过的地方 (places) ❌ 不支持子文件夹(可选支持)
命名建议: 使用地点名称。
places/├── 成都.md # 成都旅行├── 杭州西湖.md # 西湖游玩├── 公司.md # 公司位置├── 北京.md # 北京出差└── 故宫.md # 故宫参观说明:
- 可以是城市、地点或具体景点
- 如果同一地点去过多次,可以只创建一个文件,通过
visitCount和正文记录每次- 不建议使用子文件夹,建议扁平化管理,每个地点一个文件
8. 笔记本 (notebooks) ✅ 支持子文件夹分类(本身就是文件夹结构)
命名建议: 笔记本(文件夹)按类型命名,条目(md文件)按日期或主题命名。
notebooks/├── 日记/│ ├── _index.md # 日记本配置│ ├── 2026-04-20.md # 4月20日的日记│ ├── 2026-04-19.md # 4月19日的日记│ └── 2026-04-18.md # 4月18日的日记├── 读书笔记/│ ├── _index.md # 读书笔记配置│ ├── 2026-04-20.md # 某本书的笔记│ └── 2026-04-15.md # 另一本书的笔记├── 学习笔记/│ ├── _index.md│ └── 2026-04.md # 4月的学习汇总└── 工作日志/ ├── _index.md └── 2026-04-20.md # 4月20日的工作记录说明:
- 笔记本是文件夹,每个笔记本可以有多个条目
- 笔记本名称应体现用途:
日记、读书笔记、工作日志、灵感记录- 条目按日期命名,保持时间顺序
- 每个笔记本文件夹内必须有
_index.md文件定义笔记本配置
9. 番组计划 (bangumi) ✅ 支持子文件夹分类
命名建议: 按类型分子文件夹,文件名使用作品名称。
bangumi/├── anime/ # 动画│ ├── 进击的巨人.md│ ├── 鬼灭之刃.md│ └── 咒术回战.md├── book/ # 书籍│ ├── 人类简史.md│ └── 活着.md├── music/ # 音乐│ ├── 周杰伦专辑.md│ └── 泰勒专辑.md├── game/ # 游戏│ ├── 王者荣耀.md│ └── 原神.md└── real/ # 影视 ├── 肖申克的救赎.md ├── 泰坦尼克号.md └── 盗梦空间.md说明:
- 子文件夹按作品类型划分: anime、book、music、game、real
- 文件名使用作品名称(中文名优先)
- 同一作品只创建一个文件,通过 frontmatter 字段记录状态变化
命名原则总结
- 语义化: 名称应准确反映内容含义
- 简洁: 避免过长的名称,但也不要过于简短(如
a.md、1.md) - 一致性: 相同类型的内容保持相同的命名风格
- 中文优先: 推荐使用中文命名,与功能模块的语义匹配
- 避免特殊字符: 不要在名称中使用
:、/、\、*、?等特殊字符
文章系统 (posts)
路径
src/content/posts/
创建文章
在 src/content/posts/ 下创建 .md 或 .mdx 文件:
---title: 我的第一篇文章published: 2026-04-18description: 这是文章描述tags: - 标签1 - 标签2category: 分类名称pinned: falseimage: https://example.com/cover.jpg---
文章正文内容...字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | string | 是 | - | 文章标题,显示在页面标题和列表中 |
published | string/Date | 是 | - | 发布日期,格式 YYYY-MM-DD |
description | string | 否 | - | 文章描述,显示在列表页的卡片摘要中 |
tags | string[] | 否 | [] | 标签数组,用于文章分类和筛选 |
category | string | 否 | - | 分类名称,用于按分类展示文章 |
pinned | boolean | 否 | false | 是否置顶,置顶文章会显示在列表最前面 |
image | string | 否 | - | 封面图 URL,建议尺寸 1200x630 |
draft | boolean | 否 | false | 是否为草稿,草稿不会显示在列表中 |
comment | boolean | 否 | true | 是否开启评论,设为 false 则禁用评论 |
updated | string/Date | 否 | - | 最后更新日期,显示在文章底部 |
子目录
支持在 posts/ 下创建子目录组织文章:
posts/├── 技术/│ └── docker.md├── 生活/│ └── daily.md└── 示例.md子目录名称会自动作为分类使用,如上面的文章会属于”技术”或”生活”分类。
日常动态 (moments)
路径
src/content/moments/
创建动态
在 src/content/moments/ 下创建 .md 文件:
---author: 团子和蛋糕avatar: https://example.com/avatar.jpgpublished: 2026-04-18images: photo1.jpg, photo2.jpg, photo3.jpgtags: - 日常location: 上海device: iPhone 15 Pro---
动态正文内容...注意:
images字段使用逗号分隔的字符串格式,不使用数组。
字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
author | string | 否 | siteConfig.author | 作者名称,显示在动态卡片上 |
avatar | string | 否 | siteConfig.avatar | 头像 URL |
published | string/Date | 是 | - | 发布时间,用于排序和显示 |
images | string | 否 | - | 图片路径,逗号分隔(注意不是数组),图片放在 public/images/moments/ 目录 |
tags | string[] | 否 | [] | 标签数组 |
location | string | 否 | - | 地点名称 |
device | string | 否 | - | 设备信息,如 “iPhone 15 Pro” |
图片使用
- 将图片放入
public/images/moments/目录 - 在 frontmatter 中使用文件名引用:
images: photo1.jpg, photo2.jpg - 支持 jpg、png、gif、webp 格式
生活记录 (life)
生活记录是本博客的核心功能,包括健康追踪、想法管理、打卡、规划等多个模块。
健康记录 ❌ 不支持子文件夹(建议扁平化管理)
健康记录包含三个子模块:运动、睡眠、饮食,都在 src/content/life/health/ 下。
运动 (workout)
路径: src/content/life/health/workout/
---date: 2026-04-18workoutType: 户外跑步runKm: 5.2workoutMinutes: 30stepsToday: 8000heartRateAvg: 135caloriesBurned: 320---
今天跑步感觉不错,跑完了感觉很轻松。| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
date | string/Date | 是 | - | 运动日期 |
workoutType | string | 否 | 锻炼 | 运动类型,如 “户外跑步”、“健身房力量训练”、“游泳” 等 |
runKm | number | 否 | 0 | 跑步距离(公里),用于统计总跑量和月度跑量 |
workoutMinutes | number | 否 | 0 | 运动时长(分钟) |
stepsToday | number | 否 | 0 | 当日步数 |
heartRateAvg | number | 否 | - | 平均心率 |
caloriesBurned | number | 否 | - | 消耗卡路里 |
睡眠 (sleep)
路径: src/content/life/health/sleep/
---date: 2026-04-17sleepHours: 7.5sleepQuality: 4wakeUpCount: 1notes: 晚上喝水太多,中间起来上厕所了一次---
记录一下今天的睡眠情况。| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
date | string/Date | 是 | - | 睡眠日期(指当晚的睡眠) |
sleepHours | number | 是 | - | 睡眠时长(小时),用于计算平均睡眠时间 |
sleepQuality | number | 否 | 3 | 睡眠质量评分,1-5 分,5 分最好 |
wakeUpCount | number | 否 | 0 | 夜间醒来次数 |
notes | string | 否 | - | 备注说明 |
饮食 (food)
路径: src/content/life/health/food/
---date: 2026-04-18allowedFoods: - 西兰花 - 鸡胸肉 - 糙米饭avoidFoods: - 奶茶 - 炸鸡breakfast: 燕麦粥 + 鸡蛋lunch: 沙拉 + 全麦面包dinner: 清蒸鱼 + 蔬菜snacks: 坚果一小把notes: 今天控制得不错,只吃了坚果作为零食---
记录今天的饮食情况。| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
date | string/Date | 是 | - | 记录日期 |
allowedFoods | string[] | 否 | [] | 推荐/计划吃的食物列表 |
avoidFoods | string[] | 否 | [] | 需要避免的食物列表 |
breakfast | string | 否 | - | 早餐内容 |
lunch | string | 否 | - | 午餐内容 |
dinner | string | 否 | - | 晚餐内容 |
snacks | string | 否 | - | 零食记录 |
notes | string | 否 | - | 备注说明 |
奇思妙想
想法/点子管理,用于记录突然的想法、计划、目标等。
路径: src/content/life/ideas/
---title: 晨跑计划content: 每天早上6点起床跑步30分钟createdAt: 2026-04-01completedAt: 2026-04-10label: 健康priority: high---
详细描述我的晨跑计划,包括目标、具体安排等。| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | string | 否 | - | 想法标题,简短概括 |
content | string | 是 | - | 想法内容,详细描述 |
createdAt | string/Date | 是 | - | 创建时间,用于排序 |
completedAt | string/Date | 否 | - | 完成时间。有值表示已完成,无值表示待完成 |
label | string | 否 | - | 标签/分类,如 “健康”、“工作”、“学习” |
priority | string | 否 | normal | 优先级:high、normal、low |
完成判断逻辑
系统通过 completedAt 字段判断想法是否完成:
- 已完成:
completedAt有值(日期) - 待完成:
completedAt为空
不需要设置 status 字段。
打卡记录
用于追踪习惯养成和日常打卡。
路径: src/content/life/checkin/
---name: 早睡早起description: 23点前入睡,7点前起床checkins: - 2026-04-01 - 2026-04-02 - 2026-04-03 - 2026-04-04---
养成健康的作息习惯,保持充沛精力。字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 打卡项目名称,如 “每日阅读”、“早起”、“喝水” |
description | string | 否 | - | 项目描述,说明打卡规则 |
checkins | string[] | 否 | [] | 打卡日期数组,格式 YYYY-MM-DD |
$schema | string | 否 | - | JSON Schema 标识 |
打卡说明
- 打卡方式: 在
checkins数组中添加日期字符串即可 - 日期格式: 使用
YYYY-MM-DD格式 - 每次打卡: 在数组中添加一个新的日期条目
- 排序: 系统会自动按日期排序显示
示例:添加新打卡
当完成一次打卡后,在 checkins 数组中添加新日期:
checkins: - 2026-04-01 - 2026-04-02 - 2026-04-03 # 添加新打卡 - 2026-04-21日常规划
用于规划和安排日常作息、习惯养成计划等。
路径: src/content/life/routines/
---name: 晨跑计划time: 早晨 6:30-7:30icon: 🏃color: "#22c55e"description: 每天早上进行30分钟有氧运动updatedAt: 2026-04-18---
## 目标
保持健康的身体状态,提高一天的精力。
## 具体安排
1. 热身 5 分钟2. 慢跑 20 分钟3. 拉伸 5 分钟| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 规划名称 |
time | string | 否 | - | 时间安排描述,如 “早晨 6:30-7:30”、“晚上 10:00” |
icon | string | 否 | 📋 | 图标 emoji |
color | string | 否 | - | 主题色,十六进制格式 |
description | string | 否 | - | 简短描述 |
updatedAt | string/Date | 否 | - | 最后更新时间 |
正文内容支持 Markdown 格式,可以详细描述计划内容、目标、具体安排等。
去过的地方
记录旅行足迹和到访过的地点。
路径: src/content/life/places/
---province: 四川省city: 成都district: 武侯区date: 2026-04-10visitCount: 3experience: 美食之城,非常喜欢这里的火锅和串串highlights: - 春熙路 - 太古里 - 武侯祠photos: - Chengdu_1.jpg - Chengdu_2.jpg---
成都之旅记录,这次是第三次来成都了。| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
province | string | 是 | - | 省份/直辖市/自治区 |
city | string | 是 | - | 城市名称 |
district | string | 否 | - | 区县/城区(可选) |
date | string/Date | 是 | - | 到访日期 |
visitCount | number | 否 | 1 | 到访次数,第几次来这个城市 |
experience | string | 否 | - | 整体体验/感受 |
highlights | string[] | 否 | [] | 亮点/推荐地点列表 |
photos | string[] | 否 | [] | 照片文件名,存放在 public/images/places/ |
rating | number | 否 | - | 评分 1-5 |
正文内容支持 Markdown,可以详细记录旅行见闻。
笔记本
笔记本功能用于创建个人日记本,每个笔记本是一个文件夹。
路径: src/content/life/notebooks/
创建步骤
- 在
src/content/life/notebooks/下创建文件夹 - 在文件夹内创建
_index.md或_index.json文件定义笔记本 - 在文件夹内创建
.md文件作为日记条目
目录结构
notebooks/└── 日记/ ├── _index.md # 笔记本配置 ├── 2026-04-18.md # 日记条目 ├── 2026-04-17.md └── 2026-04-16.md_index.md 配置
---name: 日记cover: diary-cover.jpgsummary: 记录每天的生活点滴color: "#ec4899"icon: 📖---
这里是笔记本的详细描述...| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 笔记本名称 |
cover | string | 否 | - | 封面图片 |
summary | string | 否 | - | 笔记本简介 |
color | string | 否 | - | 主题色 |
icon | string | 否 | 📔 | 图标 emoji |
日记条目内容
---date: 2026-04-18name: 今天很开心mood: happyweather: sunnytags: - 日常---
今天发生了一些有趣的事情...
## 今天做了什么
- 上午去了图书馆- 下午和朋友一起喝咖啡- 晚上看了部电影
## 感想
今天过得很充实!| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
date | string/Date | 是 | - | 日记日期 |
name | string | 否 | 文件名 | 日记标题/名称,用于在列表中显示 |
mood | string | 否 | - | 心情/情绪 |
weather | string | 否 | - | 天气 |
tags | string[] | 否 | [] | 标签 |
正文使用 Markdown 格式书写日记内容。
番组计划 (bangumi)
用于记录动漫、书籍、音乐、游戏、影视的观看/阅读/游玩进度。
路径: src/content/bangumi/
支持 .md, .yaml, .yml 格式:
---title: 攻壳机动队name_cn: 攻壳机动队 Stand Alone Complexcategory: animestatus: 2image: https://example.com/cover.jpglink: https://bgm.tv/subject/1score: 10tags: - 科幻 - 神作 - 赛博朋克published: 2026-01-01finishDate: 2026-01-15episodes: 26comments: 最喜欢的动画没有之一---
关于这部作品的详细评论和感想...通用字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | string | 是 | - | 作品标题(英文/原名) |
name_cn | string | 否 | - | 中文名称 |
category | string | 否 | anime | 作品类型 |
status | number | 否 | 2 | 状态代码(1-5) |
image | string | 是 | - | 封面图 URL |
link | string | 是 | - | Bangumi 链接 |
score | number | 否 | - | 个人评分 1-10 |
tags | string[] | 否 | [] | 标签 |
published | string/Date | 否 | - | 作品发布年份/日期 |
comment | string | 否 | - | 简短评论 |
status 状态码
| 值 | 状态 | 说明 |
|---|---|---|
| 1 | 想看 | 想要观看/阅读/游玩 |
| 2 | 看过 | 已完成观看/阅读/游玩 |
| 3 | 在看 | 正在观看/阅读/游玩 |
| 4 | 搁置 | 暂时搁置 |
| 5 | 抛弃 | 放弃 |
category 类型
| 值 | 类型 | 说明 |
|---|---|---|
| anime | 动画 | 番剧、剧场版、OVA |
| book | 书籍 | 小说、漫画、杂志 |
| music | 音乐 | 专辑、单曲 |
| game | 游戏 | 电子游戏、桌游 |
| real | 影视 | 电影、电视剧、纪录片 |
分类专属字段
anime 动画:
| 字段 | 类型 | 说明 |
|---|---|---|
episodes | number | 总集数 |
duration | string | 单集时长,如 “24min” |
book 书籍:
| 字段 | 类型 | 说明 |
|---|---|---|
author | string | 作者 |
pages | number | 总页数 |
game 游戏:
| 字段 | 类型 | 说明 |
|---|---|---|
platform | string | 平台,如 “PC”, “Switch”, “PS5” |
playTime | number | 游玩时长(小时) |
侧边栏组件
侧边栏组件在 src/config/sidebarConfig.ts 中配置。
可用组件
| 组件 | 说明 |
|---|---|
profile | 用户资料卡片,显示头像、名称、简介 |
announcement | 公告通知 |
music | 音乐播放器(需要音乐服务配置) |
categories | 文章分类列表 |
tags | 标签云 |
lifeStats | 生活统计数据面板 |
relationship | 恋爱/纪念日计时器 |
quoteOfTheDay | 今日一言/随机语录 |
recentItems | 最近更新的文章列表 |
stats | 站点统计(文章数、字数等) |
calendar | 更新日历 |
sidebarToc | 文章目录(仅文章页显示) |
siteHeatmap | 更新热力图 |
advertisement | 广告位(可放置自定义内容) |
组件配置
{ type: "组件名称", enable: true, // 是否启用 position: "sticky", // 布局位置:sticky(粘性)、normal(普通流) showOnPostPage: true, // 是否在文章页显示 showOnNonPostPage: true, // 是否在非文章页显示 // 其他组件特定配置...}各组件配置详情
profile
{ type: "profile", enable: true, position: "sticky", showOnPostPage: false, showOnNonPostPage: true,}lifeStats
{ type: "lifeStats", enable: true, position: "normal", showOnPostPage: false, showOnNonPostPage: true,}relationship
{ type: "relationship", enable: true, position: "sticky", showOnPostPage: false, showOnNonPostPage: true, startDate: "2020-01-01", // 纪念日日期 label: "在一起", // 显示标签}quoteOfTheDay
{ type: "quoteOfTheDay", enable: true, position: "normal", showOnPostPage: true, showOnNonPostPage: true, source: "hitokoto", // 语录来源:hitokoto(一言 API) 或 local(本地配置)}calendar
{ type: "calendar", enable: true, position: "normal", showOnPostPage: false, showOnNonPostPage: true,}评论系统
博客使用 Waline 作为评论系统。
评论配置
在 src/config/siteConfig.ts 中配置 Waline:
comment: { waline: { serverURL: "https://your-server.vercel.app", lang: "zh-CN", }}字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
serverURL | string | 是 | Waline 服务地址 |
lang | string | 否 | 语言设置 |
评论启用位置
评论功能在以下位置可用:
- 文章详情页: 默认开启,可通过 frontmatter
comment: false关闭 - 日常动态页:
/moments/页面默认开启 - 留言板:
/guestbook/页面
配置文件
siteConfig.ts
主要配置文件,位于 src/config/siteConfig.ts
| 配置项 | 类型 | 说明 |
|---|---|---|
title | string | 站点标题,显示在浏览器标签和首页 |
description | string | 站点描述,用于 SEO |
author | string | 作者名称 |
avatar | string | 默认头像 URL |
themeColor | object | 主题色配置 |
themeColor.hue | number | 色调 0-360 |
themeColor.saturation | number | 饱和度 0-100 |
navbar | array | 顶部导航栏配置 |
favicon | string | 网站图标路径 |
pages | object | 页面开关 |
pages.sponsor | boolean | 是否启用赞助页面 |
pages.guestbook | boolean | 是否启用留言板 |
pages.bangumi | boolean | 是否启用番组计划 |
postListLayout | string | 文章列表布局:grid、list、masonry |
pagination | object | 分页配置 |
mapConfig | object | 地图配置(高德地图 API) |
comment | object | 评论系统配置 |
navBarConfig.ts
导航栏配置文件,位于 src/config/navBarConfig.ts
[ { name: "首页", url: "/" }, { name: "文章", url: "/posts/" }, { name: "生活", url: "/life/" }, { name: "工具", url: "/tools/", children: [ // 下拉菜单 { name: "工具1", url: "/tools/tool1/" }, { name: "工具2", url: "/tools/tool2/" }, ] },]常见问题
Q: 如何禁用某个页面?
在 siteConfig.ts 中修改 pages 配置:
pages: { sponsor: false, // 禁用赞助页 guestbook: false, // 禁用留言板 bangumi: false, // 禁用番组页}Q: 如何添加自定义页面?
- 在
src/pages/下创建新的.astro文件 - 使用现有的 Layout 组件包装内容
- 在
navBarConfig.ts中添加导航链接
Q: 如何修改主题色?
在 siteConfig.ts 中修改 themeColor.hue 值(0-360):
themeColor: { hue: 200, // 蓝色调 saturation: 70,}Q: 如何添加新内容类型?
- 在
src/content/下创建新的文件夹 - 创建对应的 schema 定义(可选)
- 在
src/pages/下创建展示页面 - 更新导航配置
Q: 图片应该放在哪里?
- 文章/生活记录图片: 直接放在正文中,图片放入
public/images/目录 - 生活记录图片:
- moments:
public/images/moments/ - places:
public/images/places/
- moments:
- 笔记本图片: 放入
public/images/notebooks/
更新日志
- 2026-04-21: 新增相册(Album)、导航(Daohang)、弹幕(Danmu)、特殊页面(Spec)功能说明;更新打卡记录的正确格式;补充高级功能章节
- 2026-04-20: 新增命名规范章节,详细说明各功能模块的文件和文件夹命名建议;新增子文件夹分类说明,明确标注哪些功能支持子文件夹分类
- 2026-04-18: 完善文档,添加所有字段详细说明
- 2026-04-10: 添加番组计划详细说明
- 2026-04-01: 初始版本
相册 (Album)
用于展示照片集,以精美的拍立得风格呈现。
路径: src/content/album/
创建相册
---title: 2026年春天subtitle: 记录春日里的美好时光date: 2026-04-01location: 郑州cover: https://example.com/cover.jpgtags: - 春天 - 户外photos: - src: https://example.com/photo1.jpg alt: 樱花盛开 caption: 校园里的樱花开了 - src: https://example.com/photo2.jpg alt: 踏青 caption: 和朋友一起去踏青---
2026年的春天,记录下每一个美好的瞬间。字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
title | string | 是 | - | 相册标题 |
subtitle | string | 否 | - | 副标题/描述 |
date | string/Date | 是 | - | 相册日期 |
location | string | 否 | - | 拍摄地点 |
cover | string | 否 | - | 封面图 URL |
tags | string[] | 否 | [] | 标签数组 |
photos | array | 是 | [] | 照片数组 |
draft | boolean | 否 | false | 是否为草稿 |
photos 数组项
photos 支持两种格式:
简单格式(仅 URL):
photos: - https://example.com/photo1.jpg - https://example.com/photo2.jpg完整格式(带元数据):
photos: - src: https://example.com/photo1.jpg alt: 照片描述 caption: 照片说明/标题照片数量显示
相册卡片会根据照片数量显示不同的堆叠效果:
- 3张及以上: 显示三层拍立得堆叠效果
- 2张: 显示两层错位效果
- 1张: 显示单张照片
- 超过3张: 在顶层照片显示 “+N” 徽章
导航 (Daohang)
用于展示常用网站链接和工具导航,支持分类管理和特色推荐。
路径: src/content/daohang/
创建导航项
---name: Cloudflareurl: https://dash.cloudflare.com/icon: material-symbols:clouddescription: 全球CDN与网络安全服务category: 常用网站tags: [云服务, CDN]color: "#f97316"image: https://example.com/icon.pngfeatured: trueorder: 10---
网站CDN加速、DNS管理、安全防护一站式平台。字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 网站/工具名称 |
url | string | 是 | - | 网站链接 |
icon | string | 否 | - | Material Symbols 图标名 |
description | string | 否 | - | 简短描述 |
category | string | 否 | 未分类 | 分类名称 |
tags | string[] | 否 | [] | 标签数组 |
color | string | 否 | - | 主题色(十六进制) |
image | string | 否 | - | 自定义图标/图片 |
featured | boolean | 否 | false | 是否推荐展示 |
order | number | 否 | 0 | 排序权重,数字越小越靠前 |
Icon 图标使用
可以使用 Material Symbols 图标库:
icon: material-symbols:home-outlineicon: material-symbols:cloudicon: material-symbols:code访问 Material Symbols 查看可用图标。
命名规范
导航项建议使用数字前缀进行排序:
daohang/├── 01-tuanzi-email.md # 第1个分类下的第1个├── 02-tuanzi-photo.md # 第2个├── 10-cloudflare.md # 第10个分类├── 20-emoji-dict.md├── 30-image-converter.md├── 40-fomalhaut.md├── 41-haiyong.md├── 42-moewah.md├── 50-qwerty-learner.md├── 60-firefly-docs.md├── 70-maptiler.md弹幕 (Danmu)
留言板功能,用户可以在留言板上发送弹幕风格的留言。
路径: src/content/danmu/
发送弹幕
---nickname: 小明avatar: https://example.com/avatar.jpgtime: 2026-04-18---
保持热爱,奔赴山海字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
nickname | string | 是 | - | 留言者昵称 |
avatar | string | 否 | 默认头像 | 头像 URL |
time | string | 否 | - | 留言时间 |
正文内容为弹幕显示的文字。
特殊页面 (Spec)
特殊内容页面,包括关于、关于我、友链、项目推荐、留言板等。
路径: src/content/spec/
1. 关于页面 (about.md)
---title: 关于我description: 个人介绍页面---
# 关于我 / About Me
你好!我是 **团子和蛋糕**,一个在数字世界中默默无闻的一片叶子。
## 联系方式
- GitHub: [链接](https://github.com/xxx)- Email: [邮箱](mailto:example@example.com)2. 友链页面 (friends.md)
---title: 友情链接description: 与优秀的朋友们一起成长---
## 友链信息
站点名称: 团子和蛋糕站点链接: https://blog.example.com头像链接: https://example.com/avatar.jpg
## 申请方式
请将网站信息发送邮件至:xxx@example.com3. 项目推荐 (projects.md)
---title: 常用网站description: 精选优质开源项目和工具---
## 推荐说明
这里收集了我日常使用的优质项目和工具。4. 留言板 (guestbook.md)
---title: 留言板description: 在这里留下你的足迹---
- 请保持友善和尊重- 欢迎分享你的想法文章进阶功能
高级功能
博客支持多种高级功能,可以在文章中灵活使用:
1. 代码块主题
使用 code shortcode 指定代码块语言和标题:
{% raw %}{% code "javascript" %}const greeting = "Hello World";{% /code %}{% endraw %}2. 提醒块 (Callouts)
支持多种主题的提醒块:
> [!NOTE]> 这是一条普通笔记
> [!TIP]> 这是一条提示
> [!WARNING]> 这是一条警告
> [!CAUTION]> 这是一条危险警告主题类型:github、obsidian、vitepress(在 siteConfig.ts 中配置 rehypeCallouts.theme)
3. GitHub 卡片
嵌入 GitHub 仓库信息:
{% raw %}{% github repo="CuteLeaf/Firefly" %}{% endraw %}4. 嵌入组件
支持嵌入多种内容类型:
- 音乐播放器
- 视频
- 幻灯片
- CodePen 等
5. 公式支持
支持 LaTeX 数学公式:
行内公式:$E = mc^2$
块级公式:
$$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$6. 图片灯箱
图片支持点击放大查看,使用 Fancybox 效果。
7. 自定义标题样式
## 普通标题### 带图标标题文章置顶
在 frontmatter 中设置 pinned: true 可以置顶文章,置顶文章会显示在列表最前面。
文章系列
可以通过标签来组织系列文章:
tags: - Java基础 - 系列:集合自定义上/下篇
在 frontmatter 中手动指定上下篇文章:
prevTitle: 上一篇文章标题prevSlug: 上一篇文章的slugnextTitle: 下一篇文章标题nextSlug: 下一篇文章的slug许可证设置
licenseName: CC BY-NC-SA 4.0licenseUrl: https://creativecommons.org/licenses/by-nc-sa/4.0/高级功能配置
许可证配置 (licenseConfig.ts)
export const licenseConfig = { enable: true, default: { name: "CC BY-NC-SA 4.0", url: "https://creativecommons.org/licenses/by-nc-sa/4.0/", },};公告配置 (announcementConfig.ts)
export const announcementConfig = { enable: true, // 可以是字符串或字符串数组 content: "欢迎来到我的博客!",};背景壁纸 (backgroundWallpaper.ts)
export const backgroundWallpaper = { enable: true, url: "https://example.com/bg.jpg",};看板娘 (pioConfig.ts)
export const pioConfig = { enable: false, model: "pxl化模型", apiVersion: 34, hidden: false,};Live2D 模型 (featureConfig.ts)
export const featureConfig = { live2d: { enable: false, model: { // Live2D 模型配置 }, },};音乐播放器 (musicConfig.ts)
export const musicConfig = { enable: false, server: "tencent", // netease, tencent, xiami, kugou id: "歌曲ID", type: "song", // song, playlist, album};头像配置 (profileConfig.ts)
export const profileConfig = { enable: true, avatar: "https://example.com/avatar.jpg", name: "团子和蛋糕", bio: "在数字世界中默默无闻的一片叶子", socials: [ { name: "GitHub", url: "https://github.com/xxx" }, { name: "Email", url: "mailto:xxx@example.com" }, ],};赞助配置 (sponsorConfig.ts)
export const sponsorConfig = { enable: true, title: "赞助作者", description: "如果觉得博客对你有帮助,可以请作者喝杯咖啡~", methods: [ { name: "微信支付", image: "/images/sponsor/wechat.png", }, { name: "支付宝", image: "/images/sponsor/alipay.png", }, { name: "爱发电", image: "/images/sponsor/afdian.png", }, ],};关系计时器 (relationshipConfig.ts)
export const relationshipConfig = { enable: true, startDate: "2020-01-01", // 纪念日日期 label: "在一起", // 显示标签 updateInterval: 3600000, // 更新间隔(毫秒)};SEO 与统计
站点配置 (siteConfig.ts)
| 配置项 | 说明 |
|---|---|
title | 站点标题 |
subtitle | 站点副标题 |
site_url | 站点 URL |
description | 站点描述(用于 SEO) |
keywords | 站点关键词 |
author | 作者名称 |
favicon | 网站图标 |
统计分析 (siteConfig.ts)
analytics: { // Google Analytics ID googleAnalyticsId: "G-XXXXXXXXXX", // Microsoft Clarity ID microsoftClarityId: "XXXXXXXX",},OpenGraph 图片
// 是否生成 OpenGraph 图片generateOgImages: false,RSS 订阅
博客自动生成 RSS 订阅源,访问 /rss.xml 即可订阅。
主题定制
主题色配置
themeColor: { hue: 208, // 色调 0-360 saturation: 70, // 饱和度 0-100 fixed: false, // 是否隐藏主题选择器 defaultMode: "system", // light, dark, system},预设主题色参考
| hue 值 | 颜色 |
|---|---|
| 0 | 红色 |
| 30 | 橙色 |
| 45 | 黄色 |
| 120 | 绿色 |
| 180 | 青色 |
| 200 | 天蓝色 |
| 220 | 蓝色 |
| 250 | 蓝紫色 |
| 280 | 紫色 |
| 330 | 粉色 |
| 345 | 玫红色 |
页面宽度
pageWidth: 100, // 单位:rem,数值越大内容区域越宽卡片样式
card: { border: true, // 是否显示卡片边框和阴影},部署与维护
构建命令
# 开发调试npm run dev
# 生产构建npm run build
# 预览构建结果npm run preview
# 部署到 GitHub Pagesnpm run deploy环境变量
可以在 .env 文件中配置:
# 公开环境变量PUBLIC_SITE_URL=https://your-site.com
# 私有环境变量PRIVATE_VARIABLE=value性能优化
图片优化
imageOptimization: { formats: "webp", // avif, webp, both quality: 85, // 1-100},字体配置
在 fontConfig.ts 中配置中文字体和等宽字体:
fontConfig: { sans: ["Inter", "Noto Sans SC"], mono: ["JetBrains Mono", "Fira Code"],},常用问题
Q: 如何禁用某个功能?
将对应配置中的 enable 设为 false。
Q: 如何自定义页面?
- 在
src/pages/下创建新的.astro文件 - 使用 Layout 组件包装内容
- 在
navBarConfig.ts中添加导航
Q: 如何修改备案信息?
在 footerConfig.ts 中配置:
footerConfig: { icp: { enable: true, code: "备案号", url: "https://beian.miit.gov.cn/", },},附录:页面路径一览
| 功能 | 路径 | 说明 |
|---|---|---|
| 首页 | / | 博客首页 |
| 文章列表 | /posts/ | 全部文章 |
| 文章详情 | /posts/[slug]/ | 单篇文章 |
| 归档 | /archive/ | 按时间归档 |
| 分类 | /categories/ | 按分类查看 |
| 标签 | /tags/ | 按标签查看 |
| 搜索 | /search/ | 文章搜索 |
| 生活 | /life/ | 生活记录首页 |
| 健康 | /life/health/ | 健康数据 |
| 打卡 | /life/checkin/ | 习惯打卡 |
| 想法 | /life/ideas/ | 奇思妙想 |
| 日记 | /life/notebooks/ | 笔记本 |
| 规划 | /life/routines/ | 日常规划 |
| 地点 | /life/places/ | 去过的地点 |
| 相册 | /album/ | 照片集 |
| 动态 | /moments/ | 日常动态 |
| 番组 | /bangumi/ | 番组计划 |
| 番组详情 | /bangumi/[slug]/ | 番组详情 |
| 友链 | /friends/ | 友情链接 |
| 留言板 | /guestbook/ | 留言板 |
| 关于 | /about/ | 关于页面 |
| 赞助 | /sponsor/ | 赞助页面 |
| RSS | /rss.xml | RSS 订阅源 |
| 地图 | /map/ | 足迹地图 |
附录:Content Schema 概览
博客使用 Astro Content Collections,所有内容定义在 src/content/config.ts 中:
| Collection | 路径 | 主要用途 |
|---|---|---|
posts | src/content/posts/ | 博客文章 |
moments | src/content/moments/ | 日常动态 |
album | src/content/album/ | 相册 |
daohang | src/content/daohang/ | 网站导航 |
bangumi | src/content/bangumi/ | 番组计划 |
life | src/content/life/*/ | 生活记录 |
danmu | src/content/danmu/ | 弹幕留言 |
spec | src/content/spec/ | 特殊页面 |
notebooks | src/content/life/notebooks/ | 笔记本 |
最后更新: 2026-04-21
支持与分享
如果这篇文章对你有帮助,欢迎分享给更多人或赞助支持!