8356 字
42 分钟

博客使用指南

2026-04-18
2026-04-21
浏览量 加载中...
AI 摘要

博客使用指南#

本文档详细介绍博客的各项功能和使用方法。

目录#

  1. 项目结构
  2. 命名规范
  3. 文章系统 (posts)
  4. 日常动态 (moments)
  5. 生活记录 (life)
  6. 相册 (album)
  7. 导航 (daohang)
  8. 弹幕 (danmu)
  9. 特殊页面 (spec)
  10. 番组计划 (bangumi)
  11. 侧边栏组件
  12. 评论系统
  13. 高级功能配置
  14. SEO 与统计
  15. 主题定制
  16. 部署与维护
  17. 常见问题
  18. 附录

项目结构#

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/进击的巨人.mdbook/人类简史.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.mda.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-晨跑.md2026-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 字段记录状态变化

命名原则总结#

  1. 语义化: 名称应准确反映内容含义
  2. 简洁: 避免过长的名称,但也不要过于简短(如 a.md1.md
  3. 一致性: 相同类型的内容保持相同的命名风格
  4. 中文优先: 推荐使用中文命名,与功能模块的语义匹配
  5. 避免特殊字符: 不要在名称中使用 :/\*? 等特殊字符

文章系统 (posts)#

路径#

src/content/posts/

创建文章#

src/content/posts/ 下创建 .md.mdx 文件:

---
title: 我的第一篇文章
published: 2026-04-18
description: 这是文章描述
tags:
- 标签1
- 标签2
category: 分类名称
pinned: false
image: https://example.com/cover.jpg
---
文章正文内容...

字段说明#

字段类型必填默认值说明
titlestring-文章标题,显示在页面标题和列表中
publishedstring/Date-发布日期,格式 YYYY-MM-DD
descriptionstring-文章描述,显示在列表页的卡片摘要中
tagsstring[][]标签数组,用于文章分类和筛选
categorystring-分类名称,用于按分类展示文章
pinnedbooleanfalse是否置顶,置顶文章会显示在列表最前面
imagestring-封面图 URL,建议尺寸 1200x630
draftbooleanfalse是否为草稿,草稿不会显示在列表中
commentbooleantrue是否开启评论,设为 false 则禁用评论
updatedstring/Date-最后更新日期,显示在文章底部

子目录#

支持在 posts/ 下创建子目录组织文章:

posts/
├── 技术/
│ └── docker.md
├── 生活/
│ └── daily.md
└── 示例.md

子目录名称会自动作为分类使用,如上面的文章会属于”技术”或”生活”分类。


日常动态 (moments)#

路径#

src/content/moments/

创建动态#

src/content/moments/ 下创建 .md 文件:

---
author: 团子和蛋糕
avatar: https://example.com/avatar.jpg
published: 2026-04-18
images: photo1.jpg, photo2.jpg, photo3.jpg
tags:
- 日常
location: 上海
device: iPhone 15 Pro
---
动态正文内容...

注意:images 字段使用逗号分隔的字符串格式,不使用数组。

字段说明#

字段类型必填默认值说明
authorstringsiteConfig.author作者名称,显示在动态卡片上
avatarstringsiteConfig.avatar头像 URL
publishedstring/Date-发布时间,用于排序和显示
imagesstring-图片路径,逗号分隔(注意不是数组),图片放在 public/images/moments/ 目录
tagsstring[][]标签数组
locationstring-地点名称
devicestring-设备信息,如 “iPhone 15 Pro”

图片使用#

  1. 将图片放入 public/images/moments/ 目录
  2. 在 frontmatter 中使用文件名引用:images: photo1.jpg, photo2.jpg
  3. 支持 jpg、png、gif、webp 格式

生活记录 (life)#

生活记录是本博客的核心功能,包括健康追踪、想法管理、打卡、规划等多个模块。

健康记录 ❌ 不支持子文件夹(建议扁平化管理)#

健康记录包含三个子模块:运动、睡眠、饮食,都在 src/content/life/health/ 下。

运动 (workout)#

路径: src/content/life/health/workout/

---
date: 2026-04-18
workoutType: 户外跑步
runKm: 5.2
workoutMinutes: 30
stepsToday: 8000
heartRateAvg: 135
caloriesBurned: 320
---
今天跑步感觉不错,跑完了感觉很轻松。
字段类型必填默认值说明
datestring/Date-运动日期
workoutTypestring锻炼运动类型,如 “户外跑步”、“健身房力量训练”、“游泳” 等
runKmnumber0跑步距离(公里),用于统计总跑量和月度跑量
workoutMinutesnumber0运动时长(分钟)
stepsTodaynumber0当日步数
heartRateAvgnumber-平均心率
caloriesBurnednumber-消耗卡路里

睡眠 (sleep)#

路径: src/content/life/health/sleep/

---
date: 2026-04-17
sleepHours: 7.5
sleepQuality: 4
wakeUpCount: 1
notes: 晚上喝水太多,中间起来上厕所了一次
---
记录一下今天的睡眠情况。
字段类型必填默认值说明
datestring/Date-睡眠日期(指当晚的睡眠)
sleepHoursnumber-睡眠时长(小时),用于计算平均睡眠时间
sleepQualitynumber3睡眠质量评分,1-5 分,5 分最好
wakeUpCountnumber0夜间醒来次数
notesstring-备注说明

饮食 (food)#

路径: src/content/life/health/food/

---
date: 2026-04-18
allowedFoods:
- 西兰花
- 鸡胸肉
- 糙米饭
avoidFoods:
- 奶茶
- 炸鸡
breakfast: 燕麦粥 + 鸡蛋
lunch: 沙拉 + 全麦面包
dinner: 清蒸鱼 + 蔬菜
snacks: 坚果一小把
notes: 今天控制得不错,只吃了坚果作为零食
---
记录今天的饮食情况。
字段类型必填默认值说明
datestring/Date-记录日期
allowedFoodsstring[][]推荐/计划吃的食物列表
avoidFoodsstring[][]需要避免的食物列表
breakfaststring-早餐内容
lunchstring-午餐内容
dinnerstring-晚餐内容
snacksstring-零食记录
notesstring-备注说明

奇思妙想#

想法/点子管理,用于记录突然的想法、计划、目标等。

路径: src/content/life/ideas/

---
title: 晨跑计划
content: 每天早上6点起床跑步30分钟
createdAt: 2026-04-01
completedAt: 2026-04-10
label: 健康
priority: high
---
详细描述我的晨跑计划,包括目标、具体安排等。
字段类型必填默认值说明
titlestring-想法标题,简短概括
contentstring-想法内容,详细描述
createdAtstring/Date-创建时间,用于排序
completedAtstring/Date-完成时间。有值表示已完成,无值表示待完成
labelstring-标签/分类,如 “健康”、“工作”、“学习”
prioritystringnormal优先级: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
---
养成健康的作息习惯,保持充沛精力。

字段说明#

字段类型必填默认值说明
namestring-打卡项目名称,如 “每日阅读”、“早起”、“喝水”
descriptionstring-项目描述,说明打卡规则
checkinsstring[][]打卡日期数组,格式 YYYY-MM-DD
$schemastring-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:30
icon: 🏃
color: "#22c55e"
description: 每天早上进行30分钟有氧运动
updatedAt: 2026-04-18
---
## 目标
保持健康的身体状态,提高一天的精力。
## 具体安排
1. 热身 5 分钟
2. 慢跑 20 分钟
3. 拉伸 5 分钟
字段类型必填默认值说明
namestring-规划名称
timestring-时间安排描述,如 “早晨 6:30-7:30”、“晚上 10:00”
iconstring📋图标 emoji
colorstring-主题色,十六进制格式
descriptionstring-简短描述
updatedAtstring/Date-最后更新时间

正文内容支持 Markdown 格式,可以详细描述计划内容、目标、具体安排等。


去过的地方#

记录旅行足迹和到访过的地点。

路径: src/content/life/places/

---
province: 四川省
city: 成都
district: 武侯区
date: 2026-04-10
visitCount: 3
experience: 美食之城,非常喜欢这里的火锅和串串
highlights:
- 春熙路
- 太古里
- 武侯祠
photos:
- Chengdu_1.jpg
- Chengdu_2.jpg
---
成都之旅记录,这次是第三次来成都了。
字段类型必填默认值说明
provincestring-省份/直辖市/自治区
citystring-城市名称
districtstring-区县/城区(可选)
datestring/Date-到访日期
visitCountnumber1到访次数,第几次来这个城市
experiencestring-整体体验/感受
highlightsstring[][]亮点/推荐地点列表
photosstring[][]照片文件名,存放在 public/images/places/
ratingnumber-评分 1-5

正文内容支持 Markdown,可以详细记录旅行见闻。


笔记本#

笔记本功能用于创建个人日记本,每个笔记本是一个文件夹。

路径: src/content/life/notebooks/

创建步骤#

  1. src/content/life/notebooks/ 下创建文件夹
  2. 在文件夹内创建 _index.md_index.json 文件定义笔记本
  3. 在文件夹内创建 .md 文件作为日记条目

目录结构#

notebooks/
└── 日记/
├── _index.md # 笔记本配置
├── 2026-04-18.md # 日记条目
├── 2026-04-17.md
└── 2026-04-16.md

_index.md 配置#

---
name: 日记
cover: diary-cover.jpg
summary: 记录每天的生活点滴
color: "#ec4899"
icon: 📖
---
这里是笔记本的详细描述...
字段类型必填默认值说明
namestring-笔记本名称
coverstring-封面图片
summarystring-笔记本简介
colorstring-主题色
iconstring📔图标 emoji

日记条目内容#

---
date: 2026-04-18
name: 今天很开心
mood: happy
weather: sunny
tags:
- 日常
---
今天发生了一些有趣的事情...
## 今天做了什么
- 上午去了图书馆
- 下午和朋友一起喝咖啡
- 晚上看了部电影
## 感想
今天过得很充实!
字段类型必填默认值说明
datestring/Date-日记日期
namestring文件名日记标题/名称,用于在列表中显示
moodstring-心情/情绪
weatherstring-天气
tagsstring[][]标签

正文使用 Markdown 格式书写日记内容。


番组计划 (bangumi)#

用于记录动漫、书籍、音乐、游戏、影视的观看/阅读/游玩进度。

路径: src/content/bangumi/

支持 .md, .yaml, .yml 格式:

---
title: 攻壳机动队
name_cn: 攻壳机动队 Stand Alone Complex
category: anime
status: 2
image: https://example.com/cover.jpg
link: https://bgm.tv/subject/1
score: 10
tags:
- 科幻
- 神作
- 赛博朋克
published: 2026-01-01
finishDate: 2026-01-15
episodes: 26
comments: 最喜欢的动画没有之一
---
关于这部作品的详细评论和感想...

通用字段#

字段类型必填默认值说明
titlestring-作品标题(英文/原名)
name_cnstring-中文名称
categorystringanime作品类型
statusnumber2状态代码(1-5)
imagestring-封面图 URL
linkstring-Bangumi 链接
scorenumber-个人评分 1-10
tagsstring[][]标签
publishedstring/Date-作品发布年份/日期
commentstring-简短评论

status 状态码#

状态说明
1想看想要观看/阅读/游玩
2看过已完成观看/阅读/游玩
3在看正在观看/阅读/游玩
4搁置暂时搁置
5抛弃放弃

category 类型#

类型说明
anime动画番剧、剧场版、OVA
book书籍小说、漫画、杂志
music音乐专辑、单曲
game游戏电子游戏、桌游
real影视电影、电视剧、纪录片

分类专属字段#

anime 动画:

字段类型说明
episodesnumber总集数
durationstring单集时长,如 “24min”

book 书籍:

字段类型说明
authorstring作者
pagesnumber总页数

game 游戏:

字段类型说明
platformstring平台,如 “PC”, “Switch”, “PS5”
playTimenumber游玩时长(小时)

侧边栏组件#

侧边栏组件在 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",
}
}

字段说明#

字段类型必填说明
serverURLstringWaline 服务地址
langstring语言设置

评论启用位置#

评论功能在以下位置可用:

  • 文章详情页: 默认开启,可通过 frontmatter comment: false 关闭
  • 日常动态页: /moments/ 页面默认开启
  • 留言板: /guestbook/ 页面

配置文件#

siteConfig.ts#

主要配置文件,位于 src/config/siteConfig.ts

配置项类型说明
titlestring站点标题,显示在浏览器标签和首页
descriptionstring站点描述,用于 SEO
authorstring作者名称
avatarstring默认头像 URL
themeColorobject主题色配置
themeColor.huenumber色调 0-360
themeColor.saturationnumber饱和度 0-100
navbararray顶部导航栏配置
faviconstring网站图标路径
pagesobject页面开关
pages.sponsorboolean是否启用赞助页面
pages.guestbookboolean是否启用留言板
pages.bangumiboolean是否启用番组计划
postListLayoutstring文章列表布局:grid、list、masonry
paginationobject分页配置
mapConfigobject地图配置(高德地图 API)
commentobject评论系统配置

导航栏配置文件,位于 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: 如何添加自定义页面?#

  1. src/pages/ 下创建新的 .astro 文件
  2. 使用现有的 Layout 组件包装内容
  3. navBarConfig.ts 中添加导航链接

Q: 如何修改主题色?#

siteConfig.ts 中修改 themeColor.hue 值(0-360):

themeColor: {
hue: 200, // 蓝色调
saturation: 70,
}

Q: 如何添加新内容类型?#

  1. src/content/ 下创建新的文件夹
  2. 创建对应的 schema 定义(可选)
  3. src/pages/ 下创建展示页面
  4. 更新导航配置

Q: 图片应该放在哪里?#

  • 文章/生活记录图片: 直接放在正文中,图片放入 public/images/ 目录
  • 生活记录图片:
    • moments: public/images/moments/
    • places: public/images/places/
  • 笔记本图片: 放入 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-01
location: 郑州
cover: https://example.com/cover.jpg
tags:
- 春天
- 户外
photos:
- src: https://example.com/photo1.jpg
alt: 樱花盛开
caption: 校园里的樱花开了
- src: https://example.com/photo2.jpg
alt: 踏青
caption: 和朋友一起去踏青
---
2026年的春天,记录下每一个美好的瞬间。

字段说明#

字段类型必填默认值说明
titlestring-相册标题
subtitlestring-副标题/描述
datestring/Date-相册日期
locationstring-拍摄地点
coverstring-封面图 URL
tagsstring[][]标签数组
photosarray[]照片数组
draftbooleanfalse是否为草稿

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: Cloudflare
url: https://dash.cloudflare.com/
icon: material-symbols:cloud
description: 全球CDN与网络安全服务
category: 常用网站
tags: [云服务, CDN]
color: "#f97316"
image: https://example.com/icon.png
featured: true
order: 10
---
网站CDN加速、DNS管理、安全防护一站式平台。

字段说明#

字段类型必填默认值说明
namestring-网站/工具名称
urlstring-网站链接
iconstring-Material Symbols 图标名
descriptionstring-简短描述
categorystring未分类分类名称
tagsstring[][]标签数组
colorstring-主题色(十六进制)
imagestring-自定义图标/图片
featuredbooleanfalse是否推荐展示
ordernumber0排序权重,数字越小越靠前

Icon 图标使用#

可以使用 Material Symbols 图标库:

icon: material-symbols:home-outline
icon: material-symbols:cloud
icon: 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.jpg
time: 2026-04-18
---
保持热爱,奔赴山海

字段说明#

字段类型必填默认值说明
nicknamestring-留言者昵称
avatarstring默认头像头像 URL
timestring-留言时间

正文内容为弹幕显示的文字。


特殊页面 (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.com

3. 项目推荐 (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]
> 这是一条危险警告

主题类型:githubobsidianvitepress(在 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: 上一篇文章的slug
nextTitle: 下一篇文章标题
nextSlug: 下一篇文章的slug

许可证设置#

licenseName: CC BY-NC-SA 4.0
licenseUrl: 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, // 是否显示卡片边框和阴影
},

部署与维护#

构建命令#

Terminal window
# 开发调试
npm run dev
# 生产构建
npm run build
# 预览构建结果
npm run preview
# 部署到 GitHub Pages
npm run deploy

环境变量#

可以在 .env 文件中配置:

Terminal window
# 公开环境变量
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: 如何自定义页面?#

  1. src/pages/ 下创建新的 .astro 文件
  2. 使用 Layout 组件包装内容
  3. 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.xmlRSS 订阅源
地图/map/足迹地图

附录:Content Schema 概览#

博客使用 Astro Content Collections,所有内容定义在 src/content/config.ts 中:

Collection路径主要用途
postssrc/content/posts/博客文章
momentssrc/content/moments/日常动态
albumsrc/content/album/相册
daohangsrc/content/daohang/网站导航
bangumisrc/content/bangumi/番组计划
lifesrc/content/life/*/生活记录
danmusrc/content/danmu/弹幕留言
specsrc/content/spec/特殊页面
notebookssrc/content/life/notebooks/笔记本

最后更新: 2026-04-21

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或赞助支持!

赞助
博客使用指南
https://blog.tsh520.cn/posts/博客指南/博客使用指南/
作者
团子和蛋糕
发布于
2026-04-18
许可协议
CC BY-NC-SA 4.0

评论区

Profile Image
团子和蛋糕
海棠花未眠,老陈总在我身边
文章
36
标签
36
动态
31
前往小窝~
我和宝宝在一起已经
---------TSH ❤️ CXY---------
---------TSH
❤️
CXY---------
0 0 0 0 0
00 "
最近更新
公告
如果你喜欢,那么欢迎来到我的世界!
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
36
动态
31
影视
41
书籍
9
游戏
2
音乐
2
分类
8
标签
36
总字数
67,799
运行时长
0
最后活动
0 天前

目录