第三章：深度定制 —— 全配置项逐行解析
我们不采用原生 fuwari 进行魔改配置，很多功能 fuwari 是没提供的，社区有很多基于 fuwari 作为基底的主题，可以让我们通过配置项的方式快速的配置现成的博客功能，而我们只需要专注于“个人化”与按需配置即可，在我经过调研之后，fuwari 主题魔改程度较高的当属于 Mizuki 主题，他保留了 fuwari 原有的简洁作为核心为设计，并添加了非常多的 feature 功能
访问 matsuzaka-yuki/Mizuki： 下一代 Material Design 3 博客主题（Astro 驱动） clone 仓库至本地环境
1
| git clone https://github.com/matsuzaka-yuki/Mizuki.git MizukiBlog
|
这一章我们将逐行“审计” src/config.ts。Mizuki 主题集成了大量第三方服务（追番、音乐、统计），请根据我的指引，申请属于你自己的 API Key，把这个空壳变成专属于你独立的个人博客
打开 src/config.ts，我们将代码分为 5 个核心区块 进行配置。
3.1 核心身份与追番服务
这部分定义了网站的基础元数据和 Bangumi（番组计划）集成。
定位代码： 第 18 - 62 行
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
|
const SITE_LANG =
/ "zh_CN"; // 🇨🇳 必改：改为 'zh_CN'，否则日期会显示英文格式
const SITE_TIMEZONE = 8;
export const siteConfig: SiteConfig = {
title: "Prorise",
subtitle: "全栈修炼手册",
siteURL: "https://your-blog.vercel.app/",
siteStartDate: "2025-12-08",
timeZone: SITE_TIMEZONE,
lang: SITE_LANG,
themeColor: {
hue: 230,
fixed: false,
},
featurePages: {
anime: true,
diary: false,
friends: true,
projects: true,
skills: true,
timeline: true,
albums: false,
devices: false,
},
navbarTitle: {
text: "Prorise",
icon: "assets/home/home.png",
},
bangumi: {
userId: "sai",
},
anime: {
mode: "bangumi",
},
};
|
获取 Bangumi ID
- 访问 bgm.tv 注册账号。
- 点击右上角头像进入个人主页。
- 观察浏览器地址栏：
https://bgm.tv/user/xxxxxx。 xxxxxx 就是你的 userId（可能是数字也可能是你自定义的英文 ID）。填入上方配置。
3.2 视觉表现与打字机
这部分控制首屏大图、字体和壁纸逻辑。
定位代码： 第 86 - 156 行 及 fullscreenWallpaperConfig
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
wallpaperMode: {
defaultMode: "none",
showModeSwitchOnMobile: "both",
},
banner: {
src: {
desktop: [
"/assets/desktop-banner/1.webp",
],
mobile: [
"/assets/mobile-banner/1.webp",
],
},
homeText: {
enable: true,
title: "Prorise Blog",
subtitle: [
"特殊的不是代码，而是写代码的人",
"Hello World",
"永远保持好奇心",
],
typewriter: {
enable: true,
speed: 100,
},
},
},
font: {
asciiFont: {
fontFamily: "ZenMaruGothic-Medium",
localFonts: ["ZenMaruGothic-Medium.ttf"],
enableCompress: true,
},
cjkFont: {
fontFamily: "萝莉体 第二版",
localFonts: ["萝莉体 第二版.ttf"],
},
},
};
export const fullscreenWallpaperConfig: FullscreenWallpaperConfig = {
opacity: 0.8,
blur: 1,
};
|
3.3 导航与社交矩阵
这部分定义了 多级菜单 和 侧边栏个人信息。
定位代码： 第 180 - 280 行
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
|
export const navBarConfig: NavBarConfig = {
links: [
LinkPreset.Home,
LinkPreset.Archive,
{
name: "Friends",
url: "/friends/",
icon: "material-symbols:group",
},
{
name: "My",
url: "/content/",
icon: "material-symbols:person",
children: [
{
name: "Projects",
url: "/projects/",
icon: "material-symbols:work",
},
],
},
],
};
export const profileConfig: ProfileConfig = {
avatar: "assets/images/avatar.webp",
name: "你的昵称",
bio: "全栈开发练习生",
links: [
{
name: "Bilibili",
icon: "fa6-brands:bilibili",
url: "https://space.bilibili.com/你的UID",
},
{
name: "GitHub",
icon: "fa6-brands:github",
url: "https://github.com/你的用户名",
},
],
};
|
3.4 媒体与互动组件
这部分是最“硬核”的，涉及 音乐播放器 API 和 评论系统。
定位代码： 第 310 - 350 行
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
export const musicPlayerConfig: MusicPlayerConfig = {
enable: true,
mode: "meting",
meting_api: "https://www.bilibili.uno/api?server=:server&type=:type&id=:id&auth=:auth&r=:r",
server: "netease",
type: "playlist",
id: "14164869977",
};
export const commentConfig: CommentConfig = {
enable: false,
twikoo: {
envId: "https://your-twikoo.vercel.app",
},
};
|
🔑 外部服务指引：获取网易云歌单 ID
- 打开网易云音乐网页版 (music.163.com)。
- 进入你喜欢的歌单页面。
- 查看 URL：
https://music.163.com/#/playlist?id=24381616。 id= 后面的数字就是你要填的 ID。注意： 部分 VIP 歌曲可能无法播放。
3.5 布局与挂件
这部分展示了 Astro 的组件化思想，你可以决定侧边栏放什么。
定位代码： 第 370 - 550 行
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
export const sidebarLayoutConfig: SidebarLayoutConfig = {
position: "both",
components: [
{ type: "profile", enable: true, order: 1, position: "top", sidebar: "left" },
{ type: "announcement", enable: true, order: 2, sidebar: "left" },
{ type: "site-stats", enable: true, sidebar: "right" },
],
};
export const sakuraConfig: SakuraConfig = {
enable: false,
sakuraNum: 21,
};
export const pioConfig: PioConfig = {
enable: false,
};
export const umamiConfig = {
enabled: false,
apiKey: "api_xxxxxxxx",
baseUrl: "https://api.umami.is",
scripts: `<script defer src="..." data-website-id="..."></script>`,
} as const;
|
3.6 内容管理指南 —— 各页面数据配置详解
配置完基础设置后，接下来需要填充各个页面的内容。Mizuki 主题采用 数据驱动 的方式管理内容，所有页面数据都集中在 src/data/ 目录下，通过修改 TypeScript 文件即可更新页面内容。
定位目录： src/data/ 和 src/content/spec/
3.6.1 番剧页面管理
番剧页面支持两种模式：Bangumi 自动同步 和 本地手动管理。
方式一：Bangumi 自动同步（推荐）
在 src/config.ts 中已配置：
1
2
3
4
5
6
| anime: {
mode: "bangumi",
},
bangumi: {
userId: "你的Bangumi用户名",
},
|
系统会自动从 Bangumi 同步你的追番列表，无需手动维护。
方式二：本地手动管理
如果需要完全自定义番剧信息，切换到本地模式：
- 修改配置：在
src/config.ts 中设置 mode: "local"
1
2
3
| anime: {
mode: "local",
},
|
- 编辑数据文件：打开
src/data/anime.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| const localAnimeList: AnimeItem[] = [
{
title: "番剧名称",
status: "watching",
rating: 9.5,
cover: "/assets/anime/封面.webp",
description: "番剧简介",
episodes: "12 episodes",
year: "2024",
genre: ["日常", "治愈"],
studio: "制作公司名称",
link: "https://bgm.tv/subject/123",
progress: 8,
totalEpisodes: 12,
startDate: "2024-01",
endDate: "2024-03",
},
];
|
- 添加封面图片：将封面图放入
public/assets/anime/ 目录，推荐使用 WebP 格式以减小体积。
3.5.2 日记页面管理
日记页面用于记录日常生活的点滴，类似朋友圈或微博。
编辑数据文件：打开 src/data/diary.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| const diaryData: DiaryItem[] = [
{
id: 1,
content: "今天天气真好，去公园散步了！",
date: "2025-01-15T10:30:00Z",
images: [
"/images/diary/photo1.jpg",
"/images/diary/photo2.jpg",
],
location: "北京朝阳公园",
mood: "开心",
tags: ["日常", "散步"],
},
{
id: 2,
content: "完成了博客的搭建，很有成就感！",
date: "2025-01-14T20:00:00Z",
tags: ["技术", "博客"],
},
];
|
添加日记图片：
- 将图片放入
public/images/diary/ 目录 - 在
images 数组中引用相对路径："/images/diary/文件名.jpg"
提示：日期使用 ISO 8601 格式（YYYY-MM-DDTHH:mm:ssZ），可以使用在线工具生成。
3.5.3 相册页面管理
相册功能采用 自动扫描 机制，只需创建文件夹和配置文件即可。
创建相册步骤：
- 创建相册文件夹：在
public/images/albums/ 下创建新文件夹（文件夹名即为相册 ID）
1
2
3
4
5
6
7
| public/images/albums/
└── my-travel-2025/ # 相册文件夹
├── info.json # 配置文件（必需）
├── cover.jpg # 封面图（必需）
├── photo1.jpg # 相册照片
├── photo2.jpg
└── ...
|
- 创建配置文件：在相册文件夹中创建
info.json
1
2
3
4
5
6
7
8
9
10
| {
"title": "我的旅行相册",
"description": "2025年夏天的美好回忆",
"date": "2025-08-01",
"location": "日本东京",
"tags": ["旅行", "风景", "夏天"],
"layout": "masonry",
"columns": 3,
"hidden": false
}
|
- 添加封面和照片：
- 封面：必须命名为
cover.jpg，建议尺寸 800×600px - 照片：支持 JPG、PNG、WebP、GIF 等格式，系统会自动扫描
外链相册模式（使用图床时）：
如果图片存储在外部图床，使用外链模式：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| {
"mode": "external",
"title": "外链相册示例",
"description": "使用外部图片链接的相册",
"date": "2024-08-28",
"cover": "https://example.com/cover.jpg",
"photos": [
{
"id": "photo-1",
"src": "https://example.com/photo1.jpg",
"alt": "图片描述",
"title": "图片标题",
"description": "详细描述",
"tags": ["标签1"],
"width": 1920,
"height": 1280
}
]
}
|
布局说明：
- Grid（网格）：适合尺寸统一的照片，照片会被裁剪为正方形
- Masonry（瀑布流）：适合不同尺寸的照片，保持原始比例，视觉效果更自然
3.5.4 设备页面管理
设备页面用于展示你使用的硬件设备。
编辑数据文件：打开 src/data/devices.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| export const devicesData: DeviceCategory = {
OnePlus: [
{
name: "OnePlus 13T",
image: "/images/device/oneplus13t.png",
specs: "Gray / 16G + 1TB",
description: "旗舰性能，哈苏影像，80W 超级闪充",
link: "https://www.oneplus.com/cn/13t",
},
],
Router: [
{
name: "GL-MT3000",
image: "/images/device/mt3000.png",
specs: "1000Mbps / 2.5G",
description: "便携式 WiFi 6 路由器，适合出差和家用",
link: "https://www.gl-inet.cn/products/gl-mt3000/",
},
],
};
|
添加设备图片：将设备图片放入 public/images/device/ 目录，推荐使用 PNG 格式（支持透明背景）。
3.5.5 友链页面管理
友链页面用于展示友情链接，支持标签分类和随机排序。
编辑数据文件：打开 src/data/friends.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| export const friendsData: FriendItem[] = [
{
id: 1,
title: "友链名称",
imgurl: "https://example.com/avatar.jpg",
desc: "友链描述或简介",
siteurl: "https://example.com",
tags: ["技术", "博客"],
},
{
id: 2,
title: "另一个友链",
imgurl: "/assets/friends/avatar2.jpg",
desc: "这是一个很棒的博客",
siteurl: "https://another-blog.com",
tags: ["设计", "前端"],
},
];
|
头像图片：
- 支持外链 URL（推荐，节省空间）
- 也支持本地路径：将图片放入
public/assets/friends/ 目录
标签用途：标签可用于前端筛选和分类显示，建议使用统一的标签体系。
友链申请说明配置：
友链页面默认底部是不会显示申请友链的说明信息，包括本站信息、申请方式和注意事项。这些内容通过 Markdown 文件管理
原理说明：
- 友链页面（src/pages/friends.astro）会自动读取 src/content/spec/friends.md 文件，默认这个文件未被创建
- 一旦文件被创建，即会使用 Astro 的 Content Collections 功能，将 Markdown 内容渲染到页面底部
- 支持完整的 Markdown 语法和 HTML 标签，可以自定义样式
配置步骤：
编辑说明文件：打开 src/content/spec/friends.md
配置模板：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
| 申请友链前请先在自己网站添加本站友链，请使用以下信息：
``` yaml
站点名称: Prorise
站点描述: One Tech website
站点链接: https://blog.prorise666.site
头像链接: https://blog.prorise666.site/assets/images/avatar.webp
```
> **注意**：请将上述信息替换为你的实际信息：
> - 站点名称：从 `src/config.ts` 的 `siteConfig.title` 获取
> - 站点描述：从 `src/config.ts` 的 `siteConfig.subtitle` 获取
> - 站点链接：从 `src/config.ts` 的 `siteConfig.siteURL` 获取
> - 头像链接：需要提供完整 URL（本地图片需使用部署后的完整路径）
---
## ✉️ 申请友链
请将您的网站信息发送邮件至：`your-email@example.com`
> **注意**：请将邮箱地址替换为你的实际邮箱
**邮件标题**：`友链申请 - [您的站点名称]`
**邮件内容模板**：
```plaintext
站点信息：
- 站点名称：[您的站点名称]
- 站点描述：[您的站点描述]
- 站点链接：[您的站点链接]
- 头像链接：[您的头像链接]
```
---
## ⚠️ 注意事项
1. **互换原则**：请先将本站添加到您的友链页面，我会在确认后添加您的友链
2. **链接维护**：如发现友链网站长期无法访问或内容违规，将会移除友链
3. **网站要求**：
- 网站内容积极向上，无违法违规信息
- 不允许含有病毒、木马、恶意代码、弹出广告以及任何危害他人计算机安全的内容
- 不能有任何含色情/反动/暴力等不法内容
- 网站能够正常访问，加载速度合理
- 网站有持续的内容更新，不是废弃站点
- 网站支持 HTTPS 访问
- 网站以原创内容为主，非纯采集站
---
💡 **小贴士**：友链不仅是网站间的连接，更是博主间的情谊纽带。让我们一起在这个数字世界中相遇、成长！
|
重要提示：
- 文件不能包含 frontmatter（--- 开头），否则会导致解析失败
- 支持 Markdown 语法：标题、列表、代码块、引用等
- 支持 HTML 标签：<div>、<style> 等，可用于自定义样式
- 修改后需要重启开发服务器才能看到效果
显示位置：
- 说明内容会显示在友链卡片网格的下方
- 使用 prose 样式类，自动应用美观的排版
3.5.6 项目展示页面管理
项目页面用于展示你的作品集，支持分类、状态筛选和技术栈标签。
编辑数据文件：打开 src/data/projects.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| export const projectsData: Project [] = [
{
id: "project-id",
title: "项目名称",
description: "项目的详细描述，可以写多行文字说明项目的功能、技术亮点等",
image: "/images/projects/cover.jpg",
category: "web",
techStack: ["React", "TypeScript", "Tailwind CSS"],
status: "completed",
liveDemo: "https://demo.example.com",
sourceCode: "https://github.com/user/repo",
visitUrl: "https://project.example.com",
startDate: "2024-01-01",
endDate: "2024-06-01",
featured: true,
tags: ["全栈", "开源"],
},
];
|
项目封面图：将封面图放入 public/images/projects/ 目录，建议尺寸 1200×600px。
状态说明：
completed：已完成的项目，会显示完成日期in-progress：进行中的项目，会显示进度标识planned：计划中的项目，会显示计划标识
3.5.7 技能展示页面管理
技能页面用于展示你的技术栈，支持分类、等级和经验年限。
编辑数据文件：打开 src/data/skills.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| export const skillsData: Skill [] = [
{
id: "javascript",
name: "JavaScript",
description: "现代 JavaScript 开发，包括 ES6+ 语法、异步编程和模块化开发",
icon: "logos: javascript",
category: "frontend",
level: "advanced",
experience: {
years: 3,
months: 6,
},
projects: ["project-id-1", "project-id-2"],
certifications: ["证书名称"],
color: "#F7DF1E",
},
];
|
图标查找：
- 访问 Iconify
- 搜索你需要的技术图标（如 “react”、“vue”、“python”）
- 复制图标名称（格式：
logos:react 或 simple-icons:github） - 填入
icon 字段
经验年限计算：
years：整数年数months：剩余月数（0-11）- 例如：3 年 6 个月 =
{ years: 3, months: 6 }
等级建议：
beginner：学习阶段，使用过但不够熟练intermediate：能够独立完成项目，解决常见问题advanced：深入理解原理，能优化和架构设计expert：精通该技术，能够指导他人
3.5.8 时间线页面管理
时间线页面用于展示你的成长历程，包括教育、工作、项目和成就。
编辑数据文件：打开 src/data/timeline.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
| export const timelineData: TimelineItem [] = [
{
id: "timeline-item-1",
title: "事件标题",
description: "事件的详细描述，可以写多行文字说明这个时间点发生了什么",
type: "education",
startDate: "2022-09-01",
endDate: "2026-06-30",
location: "北京",
organization: "北京理工大学",
position: "学生",
skills: ["Java", "Python", "JavaScript"],
achievements: [
"当前 GPA: 3.6/4.0",
"完成了数据结构与算法课程项目",
],
links: [
{
name: "项目链接",
url: "https://github.com/user/repo",
type: "project",
},
],
icon: "material-symbols: school",
color: "#059669",
featured: true,
},
];
|
时间线类型说明：
education：教育经历（如上学、培训）work：工作经历（如实习、全职工作）project：项目经历（如课程项目、个人项目）achievement：成就（如获奖、证书、比赛）
日期格式：
- 使用
YYYY-MM-DD 格式 - 不填
endDate 表示该事件仍在进行中
排序：时间线会自动按 startDate 倒序排列（最新的在前）。
3.5.9 关于页面管理
关于页面使用 Markdown 格式，更灵活地展示个人信息。
编辑内容文件：打开 src/content/spec/about.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| # 关于我
这里可以写你的个人介绍，支持完整的 Markdown 语法。
## 我的经历
- 2020-2024：就读于 XX 大学
- 2024-至今：在 XX 公司工作
## 我的技能
- 前端开发：React、Vue、TypeScript
- 后端开发：Node.js、Python
## 联系方式
- Email: your@email.com
- GitHub: [@yourusername](https://github.com/yourusername)
---
*这个网站使用 * *Astro* * 框架和 [Mizuki](https://github.com/matsuzaka-yuki/mizuki) 主题构建。*
|
Markdown 扩展语法：
Mizuki 支持丰富的 Markdown 扩展：
GitHub 卡片：
1
| :: github{repo = "user/repo"}
|
提示框：
1
2
3
4
5
6
7
8
| > [!NOTE]
> 这是一个提示
> [!WARNING]
> 这是一个警告
> [!TIP]
> 这是一个技巧
|
数学公式：
1
2
3
4
5
6
| 行内公式：$E = mc^2$
块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
|
3.5.10 管理技巧总结
数据文件位置速查表：
| 页面 | 数据文件路径 | 内容格式 |
|---|
| 番剧 | src/data/anime.ts | TypeScript 数组 |
| 日记 | src/data/diary.ts | TypeScript 数组 |
| 相册 | public/images/albums/*/info.json | JSON 配置文件 |
| 设备 | src/data/devices.ts | TypeScript 对象 |
| 友链 | src/data/friends.ts | TypeScript 数组 |
| 项目 | src/data/projects.ts | TypeScript 数组 |
| 技能 | src/data/skills.ts | TypeScript 数组 |
| 时间线 | src/data/timeline.ts | TypeScript 数组 |
| 关于 | src/content/spec/about.md | Markdown 文件 |
通用管理建议：
- ID 管理：每个数据项都需要唯一 ID，建议使用有意义的命名（如
project-blog）或递增数字 - 图片优化：所有图片建议使用 WebP 格式，并使用工具压缩以提升加载速度
- 数据备份：修改前建议先提交到 Git，方便回滚
- 批量编辑：可以使用 VS Code 的多光标功能快速编辑相似数据
启用/禁用页面：
在 src/config.ts 的 featurePages 中控制：
1
2
3
4
5
6
| featurePages: {
anime: true,
diary: false,
friends: true,
},
|
设置为 false 的页面不会生成，访问时会跳转到 404。
