🌸 Mizuki

一个现代化、功能丰富的静态博客模板，基于 Astro 构建，具有先进的功能和精美的设计。

[!WARNING]

⚠️ 项目停止更新与迁移通知

本项目（Mizuki）即将停止更新与维护。
全新全面重构版本 Shirone 现已发布，功能与本项目基本一致，并在架构与体验上进行了全面重构与优化。建议前往新项目获取最新支持与更新：
🔗 新项目仓库：https://github.com/lyraVoid/shirone

🖥️ 在线演示 | 📝 用户文档

🌏 README 语言: 中文 / English / 日本語 / 繁體中文 /

通过我们的综合文档快速开始。无论是自定义主题、配置功能，还是部署到生产环境，文档涵盖了您成功启动博客所需的所有内容。

📚 阅读完整文档 →

✨ 功能特性

🎨 设计与界面

• 基于 Astro 和 Tailwind CSS 构建
• 使用 Swup 实现流畅的动画和页面过渡
• 明暗主题切换，支持系统偏好检测
• 可自定义主题色彩、横幅轮播和全屏壁纸
• 可切换壁纸模式，并调整透明度和模糊效果
• 可配置侧边栏组件、顺序和响应式布局
• 可选的宽屏自动页面缩放
• 全设备响应式设计
• 支持自定义或系统字体模式，包括 JetBrains Mono 和中日韩字体

🔍 内容与搜索

• 基于 Pagefind 的高级搜索功能
• Markdown 和 MDX 扩展，支持语法高亮
• 交互式目录，支持自动滚动
• RSS 和 Atom 全文订阅，复用文章页面的 Markdown/MDX 管线
• 阅读时间估算
• 文章分类、标签、置顶、别名和自定义固定链接
• 可选的密码保护文章，并明确静态站点加密的安全边界

📱 特色页面

• 追番页面 - 使用本地数据、Bangumi 或 Bilibili 追踪动画
• 友链页面 - 使用卡片和标签展示友链
• 日记页面 - 分享带有文字、图片、位置、心情和标签的动态
• 相册页面 - 管理本地或外部相册，并支持可选加密
• 项目、技能、设备和时间线页面 - 展示结构化个人数据
• AI 工具页面 - 维护可筛选的工具目录
• 归档和关于页面 - 浏览文章或发布自定义介绍

🛠 技术特性

• 增强代码块，基于 Expressive Code
• 数学公式，使用 KaTeX，并支持 Mermaid 和 PlantUML 图表
• 图片增强，包括响应式尺寸、自动网格和 Fancybox 灯箱
• SEO 优化，包括站点地图、robots.txt、RSS、Atom 和可选 Open Graph 图片
• 性能优化，懒加载和缓存机制
• 评论系统，支持 Twikoo 或 Giscus
• 音乐播放器，支持本地和 Meting 模式
• Live2D 看板娘，通过 Pio 实现

🚀 快速开始

📦 安装

1. 克隆仓库：

   git clone https://github.com/LyraVoid/Mizuki.git
   cd Mizuki
   

2. 安装依赖：

   # 启用项目声明的包管理器版本
   corepack enable
   
   # 安装项目依赖
   pnpm install
   

3. 配置博客（可选）：

   • 如果只使用本地内容，请在项目根目录 .env 中设置 ENABLE_CONTENT_SYNC=false。
   • 编辑 src/config/siteConfig.ts 和 src/config/ 下的其他模块自定义站点。
   • 至少将 siteURL 替换为部署后的公开网址。

4. 启动开发服务器：

   pnpm dev
   

   博客将在 http://localhost:3000 可用

📝 内容管理

• 创建文章： pnpm new-post -- <文件名>，支持 .md 和 .mdx。
• 编辑文章： 修改 src/content/posts/ 中的文件。
• 编辑关于页或友链页内容： 修改 src/content/spec/ 中对应的文件。
• 编辑结构化页面数据： 修改 src/data/ 中对应的文件。
• 添加文章本地图片： 将图片放在文章旁边，并使用 ./cover.webp 这样的相对路径。
• 添加公共图片： 放在 public/ 下，并使用 /images/example.webp 这样的根路径。

发布前注意： 仓库中包含示例文章、页面数据、相册和图片。部署个人站点前请删除或替换这些示例内容。

🚀 部署

将博客部署到任何静态托管平台：

• Vercel： 连接 GitHub 仓库到 Vercel

• Netlify： 直接从 GitHub 部署

• GitHub Pages： 使用包含的 GitHub Actions 工作流

• Cloudflare Pages： 连接您的仓库

• 环境变量配置（可选）： 可参照 .env.example 来配置

部署前，请在 src/config/siteConfig.ts 中更新 siteURL。不要将 .env 或凭据提交到 Git；托管构建请在平台的环境变量设置中配置。

.env.example 中还包含 Bilibili 会话数据和 IndexNow 凭据等可选配置。只在需要时设置，并放在本地环境或托管平台 Secret 中，切勿提交真实值。

📝 内容编写

文章使用 src/content/posts/ 下的 .md 或 .mdx 文件，title 和 published 是必填的 frontmatter 字段。可选字段支持摘要、图片、标签、分类、草稿、置顶、评论、别名、固定链接、署名和浏览器端加密。

Markdown 和 MDX 支持提示框、KaTeX 数学公式、Expressive Code、Mermaid、PlantUML、GitHub 卡片、Wiki Link、剧透、响应式图片、图片网格、Fancybox 灯箱和 HTML 嵌入。加密文章不会进入 RSS 和 Atom，但浏览器端加密不是服务端访问控制。

PlantUML 默认使用 src/config/markdownConfig.ts 中配置的公共服务器，请勿在图表中写入密码、Token 或隐私数据。

完整字段表、写作语法、图片规则、图表、视频嵌入、加密限制和发布清单请参阅内容编写指南。

⚡ 命令

所有命令都在项目根目录运行：

🎯 配置指南

🔧 基础配置

配置已拆分到 src/config/ 下的多个模块，src/config/index.ts 是统一导出入口。主要站点设置位于 src/config/siteConfig.ts：

export const siteConfig: SiteConfig = {
  title: "您的博客名称",
  subtitle: "您的博客描述",
  siteURL: "https://example.com/", // 保留结尾斜杠
  lang: "zh_CN", // 例如 "en"、"ja" 或 "zh_TW"
  timeZone: "Asia/Shanghai", // 任意有效的 IANA 时区
  themeColor: {
    hue: 210, // 0–360
    fixed: false, // 为 true 时隐藏访客的主题色选择器
  },
  featurePages: {
    anime: true,
    diary: true,
    friends: true,
    projects: true,
    skills: true,
    timeline: true,
    albums: true,
    devices: true,
    aiTools: true,
  },
  // 其余字段请保留模板默认值。
};

其他常用配置文件：

• src/config/navBarConfig.ts — 导航链接和菜单。
• src/config/profileConfig.ts — 头像、名称、简介和社交链接。
• src/config/sidebarConfig.ts — 侧边栏组件、顺序、位置和响应式行为。
• src/config/backgroundWallpaper.ts 与 src/config/effectsConfig.ts — 壁纸和视觉特效。
• src/config/commentConfig.ts — Twikoo 或 Giscus 全局设置。评论默认关闭；使用前请设置 enable: true 并配置对应服务。
• src/config/musicConfig.ts — 音乐播放器模式和歌单来源。
• src/config/markdownConfig.ts — Wiki Link、自动图片网格和 PlantUML。
• src/config/permalinkConfig.ts — 可选的全局固定链接格式。
• src/config/expressiveCodeConfig.ts — 代码块主题和行为。

📱 特色页面内容

页面开关由 siteConfig.featurePages 控制。页面内容与页面模板分离：

不要为了修改页面内容而直接编辑 src/pages/*.astro；这些文件负责布局和渲染逻辑。

📦 代码内容分离 (可选)

Mizuki 可以将主题代码和博客内容分成两个仓库，适用于私有内容、独立版本管理或团队协作，但这是可选功能。

快速选择:

一键启用/禁用:

# 本地内容模式（推荐入门使用）
# 在 .env 中显式关闭同步
ENABLE_CONTENT_SYNC=false
pnpm dev

# 外部内容仓库模式
# 1. 复制配置示例
cp .env.example .env

# 2. 编辑 .env
ENABLE_CONTENT_SYNC=true
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git
# CONTENT_DIR=./content  # 可选，默认值即为此路径

# 3. 同步内容并启动站点
pnpm run sync-content
pnpm dev

外部内容仓库可以使用以下结构：

Mizuki-Content/
├── posts/       # .md 和 .mdx 文章
├── spec/        # 关于页、友链页等 Markdown 内容
├── data/        # 项目、技能等结构化页面数据
└── images/      # 公共图片，包括相册和文章资源

同步脚本会将这些目录映射到 src/content/posts/、src/content/spec/、src/data/ 和 public/images/。src/data/ai-tools.ts 属于代码仓库，会在同步时受到保护。

同步警告： 启用 ENABLE_CONTENT_SYNC 后，pnpm dev 和 pnpm build 会自动执行同步钩子。如果 CONTENT_DIR 已经是 Git 仓库，同步脚本会 fetch 并重置到远程 main 或 master 分支；它还可能将现有运行时目录备份为 .backup、创建目录联接或复制文件，并在代码仓库中提交同步结果。执行前请提交或备份本地内容修改，不要直接编辑同步目标文件。

私有仓库可以使用 SSH URL，或通过部署平台配置凭据。不要将 Token 写入 .env 并提交，也不要将 Token 放进公开仓库 URL。

📖 详细配置： 内容分离完整指南

🔄 迁移教程： 从单仓库迁移到分离模式

🚀 部署指南： 部署指南

📚 更多文档： 文档索引

✏️ 贡献

我们欢迎贡献！请随时提交问题和拉取请求。

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

本项目基于 Apache 许可证 2.0 - 查看 LICENSE 文件了解详情。

原始项目许可证

本项目基于 Fuwari 开发，该项目使用 MIT 许可证。根据 MIT 许可证要求，原始版权声明和许可声明已包含在 LICENSE.MIT 文件中。

第三方软件声明

Markdown 增强功能的部分实现基于 Firefly 的 MIT 许可代码改写。原始版权声明与完整许可证文本保留在 THIRD_PARTY_NOTICES.md 中。

🙏 致谢

• 基于原始 Fuwari 模板
• 灵感来源于 Yukina - 一个美丽优雅的博客模板
• 部分设计灵感来源于 Firefly 和 Twilight 模板
• 使用 Pio 实现可爱的 Live2D 看板娘插件
• 使用 Astro 和 Tailwind CSS 构建
• 图标来自 Iconify

🌸 特别感谢

• Fuwari by saicaca - 本项目所基于的原始模板。感谢您创建了如此漂亮且功能强大的模板。
• Yukina - 感谢提供设计灵感和创意，帮助塑造了这个项目。Yukina 是一个优雅的博客模板，展现了出色的设计原则和用户体验。
• Firefly - 感谢提供优秀的布局设计思路，双侧边栏布局、文章双列网格等布局，及部分小组件的设计与实现，让 Mizuki 的界面更加丰富。
• Twilight - 感谢提供灵感和技术支持。Twilight 的动态壁纸模式切换系统、响应式设计和过渡效果显著提升了 Mizuki 的使用体验。

🍀 贡献者

感谢以下贡献者对本项目做出的贡献，如有问题或建议，请提交 Issue 或 Pull Request。

⭐ Star History

⭐ 如果您觉得这个项目有帮助，请考虑给它一个星标!