Astro全面介绍及Mizuki二次元主题修改教程

Astro是一款现代静态网站生成器，而Mizuki是基于它构建的优雅二次元风格博客主题。下面为你详细介绍Astro、Mizuki主题，以及如何发文章、修改样式的完整教程。

一、Astro是什么？

Astro是一款现代化的静态网站生成器，由Astro团队开发，旨在解决传统前端框架“加载过重”的问题。它采用独特的“岛屿架构”（Islands Architecture），在构建时尽可能生成静态HTML，只在必要的地方加载JavaScript。

Astro的核心优势

特性说明
默认零JS 默认输出纯静态HTML，页面加载速度极快
岛屿架构只在需要交互的地方加载JS，其余保持静态
多框架支持同时支持React、Vue、Svelte、Solid等组件混用
内容驱动内置Markdown、MDX支持，适合博客、文档站
按需构建只打包页面实际需要的资源，优化产物大小

Astro特别适合内容型网站——博客、文档、作品集、企业官网等。它不像Next.js那样是全能框架，而是专注做好“内容展示”这一件事。

二、Mizuki主题介绍

Mizuki是一款基于Astro构建的优雅二次元风格博客主题，由开发者松坂有希创建，目前在Astro官方主题市场收录。

2.1 主题风格

Mizuki的设计理念是“融入二次元元素的优雅博客”。它的视觉风格：

· 整体简洁大气，搭配柔和的二次元色调
· 支持亮色/暗色模式，跟随系统偏好自动切换
· 可自定义主题色（通过调整色相值）
· 动态轮播横幅，支持多图切换

2.2 核心功能

功能类别具体特性
内容写作 Markdown支持、代码高亮、数学公式（KaTeX）、提示框（Admonitions）
搜索导航 Pagefind全文搜索、自动滚动目录、文章归档
特殊页面追番记录页、友链页、日记/碎碎念页、关于页、图库页
多语言内置10+语言支持（中、英、日、韩等），自动检测用户偏好
社交功能 Twikoo评论系统、RSS订阅、阅读时间估算
性能优化图片懒加载、PhotoSwipe图库预览、SEO自动优化

2.3 真实案例

有博主使用Mizuki主题搭配Vercel部署个人博客，并通过Cloudflare加速国内访问，体验流畅。该博主提到，虽然配置过程中遇到一些技术难题（如Twikoo评论、Pagefind搜索的部署问题），但最终效果令人满意。

三、如何发文章？

3.1 文章存放位置

Mizuki的所有文章都存放在src/content/posts/目录下。每篇文章是一个单独的Markdown（.md）或MDX文件。

3.2 创建新文章

有两种方式：

方式一：使用命令（推荐）

pnpm new-post 我的新文章

这会在src/content/posts/自动生成一个带基础模板的Markdown文件。

方式二：手动创建
直接在src/content/posts/新建一个.md文件，文件名会作为URL的一部分（建议用英文或拼音）。

3.3 文章头部信息（Frontmatter）

每篇文章开头必须包含以下信息（YAML格式）：

---
title: 我的第一篇博客文章      # 文章标题（必填）
published: 2024-01-15        # 发布日期（必填）
description: 这是文章的描述    # 描述，用于SEO和预览
image: ./cover.jpg           # 封面图路径（相对当前文件）
tags: [Astro, 博客, 二次元]    # 标签数组
category: 技术杂谈            # 分类
draft: false                 # 是否为草稿（true则不发布）
pinned: true                 # 是否置顶（置顶文章优先显示）
lang: zh                     # 若文章语言与站点配置不同，可单独指定

重点说明：

· 置顶功能：设置pinned: true后，文章会始终显示在列表最前面，按发布日期排序
· 草稿模式：draft: true的文章在开发环境可见，但生产构建时不会包含

3.4 文章正文写作

Mizuki支持增强的Markdown语法：

普通内容：直接写Markdown即可

提示框（Admonitions）：

> [!NOTE]
> 这是一条普通提示

> [!TIP]
> 这是一个小技巧

> [!WARNING]
> 注意这里有坑

数学公式：

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

块级公式：
$$
\sum_{i=1}^n i = \frac{n(n+1)}{2}
$$

嵌入GitHub仓库卡片：

::github{repo="matsuzaka-yuki/Mizuki"}

3.5 发布流程

写完文章后，运行pnpm build检查构建是否正常
推送到Git仓库（如GitHub）
部署平台（Vercel/Netlify）自动拉取更新并发布

四、如何修改样式？

Mizuki基于Tailwind CSS构建，所有样式都可以通过配置文件或自定义CSS修改。

4.1 快速修改主题色

这是最简单的个性化方式：

打开src/config.ts文件
找到themeColor配置项：

themeColor: {
  hue: 210,      // 修改这个数值（0-360），210是蓝色，330是粉色，45是橙色
  fixed: false,  // true则固定颜色，用户无法通过主题色选择器修改
},

修改hue值即可改变整个网站的主色调。

4.2 修改网站基础信息

同样在src/config.ts中：

export const siteConfig: SiteConfig = {
  title: "你的博客名称",
  subtitle: "你的博客副标题",
  lang: "zh-CN",  // 默认语言
  // ...其他配置
};

4.3 修改横幅轮播图

banner: {
  enable: true,   // 是否开启横幅
  src: [
    "assets/banner/1.webp",  // 在这里添加或替换图片路径
    "assets/banner/2.webp",
  ],
  carousel: {
    enable: true,
    interval: 0.8,  // 切换间隔（秒）
  },
},

图片建议放在src/assets/banner/目录下，使用WebP格式以获得更好性能。

4.4 自定义CSS

如果需要更细致的样式修改：

方法一：添加全局CSS
在src/styles/目录下创建自定义CSS文件，然后在布局组件中引入。

方法二：覆盖Tailwind类
Mizuki的组件使用Tailwind的类名，你可以通过浏览器开发者工具查看元素使用的类，然后在自己的CSS中覆盖。

方法三：修改组件源码
如果你熟悉Astro和Tailwind，可以直接修改src/components/下的组件文件。

4.5 修改特殊页面内容

页面修改位置
关于页 src/content/spec/about.md
友链页 src/content/spec/friends.md
追番页编辑src/pages/anime.astro中的数据
日记页编辑src/pages/diary.astro

五、进阶自定义

5.1 修改导航菜单

导航菜单通常在布局组件中定义，查找src/layouts/下的文件，找到导航栏组件进行修改。

5.2 添加新页面