沉眠之海

克隆Mizuki仓库#

首先，我们需要将 Mizuki 的代码下载到本地。打开终端，进入你希望存放项目的目录，执行以下命令：

1
git clone https://github.com/matsuzaka-yuki/mizuki.git my-blog
2
cd my-blog

💡 小提示：由于该项目提交历史较长（超过 900 次提交），直接克隆可能会比较慢。你可以通过添加 --depth=1 参数，使用浅克隆的方式只下载最新代码，速度会快很多：

bash

1
git clone --depth=1 https://github.com/matsuzaka-yuki/mizuki.git my-blog

安装依赖#

进入项目根目录，运行以下命令安装项目所需的所有依赖包：

1
pnpm install

如果命令执行时报错 packages field missing or empty，可以尝试删除项目根目录下的 pnpm-workspace.yaml 文件，然后重新运行安装命令。

如果你还没有安装 pnpm，请先通过 npm install -g pnpm 进行全局安装。

本地启动项目#

依赖安装完成后，运行以下命令启动本地开发服务器：

1
pnpm dev

启动过程中，你可能会看到一些关于内容目录的警告信息，这是因为项目采用了内容与主题分离的设计，暂时可以忽略。当终端出现类似下面的输出时，表示服务已成功启动：

1
 astro  v6.1.2 ready in 10330 ms
2
┃ Local    http://localhost:4321/
3
┃ Network  use --host to expose

在浏览器中访问 http://localhost:4321/

即可预览你的博客。第一次加载可能会比较慢，请耐心等待。

第一步：修改站点信息#

让博客真正成为“你自己的”，关键就在于修改 src/config.ts 配置文件。用代码编辑器打开该文件，你可以对照着本地预览界面上的文字内容，逐一将以下字段替换成自己的信息：

• site.title：博客标题
• site.description：站点描述
• site.author：作者名称
• site.url：线上访问地址（部署前记得修改为最终域名）
• social：社交账号链接（不需要的留空即可）

管理特色页面#

Mizuki 内置了番剧、日记、友链、项目等多个特色页面。你可以根据自己的需求，在 src/config.ts 中找到 featurePages 配置项，按需开启或关闭：

1
  // 特色页面开关配置（关闭未使用的页面有助于提升 SEO）
2
  featurePages: {
3
    anime: false, // 番剧页面开关
4
    diary: true, // 日记页面开关
5
    friends: true, // 友链页面开关
6
    projects: true, // 项目页面开关
7
    skills: true, // 技能页面开关
8
    timeline: true, // 时间线页面开关
9
    albums: true, // 相册页面开关
10
    devices: false, // 设备页面开关
11
  },

关闭某个页面后，别忘了将 navbarConfig 中对应的导航菜单项也注释或删除掉，保持界面整洁。其他更多个性化功能，可以参考 config.ts 文件中的详细注释，根据自己的喜好慢慢调整。

发布文章#

Mizuki 支持两种创建文章的方式，你可以任选其一：

1. 命令行方式（推荐） 在项目根目录执行以下命令，即可在 src/content/posts/ 目录下自动生成一篇带有基础 Frontmatter 的 Markdown 文件：

1
pnpm new-post 我的第一篇文章

2. 手动创建方式

   直接在 src/content/posts/ 目录下新建 .md 文件。如果需要添加文章封面图，请在该目录下新建一个与文章同名的文件夹，将封面图片和 index.md 文件一同放入其中。

每篇文章开头的 --- 包裹区域为 Frontmatter，用于定义文章的各种属性。一个基本的配置示例如下：

1
---
2
title: Mizuki博客搭建与Vercel部署
3
published: 2026-04-14
4
description: '如何搭建一个Mizuki主题的Astro博客，并通过Vercel部署，配置自定义域名让国内也能正常访问。'
5
image: './cover.webp'
6
tags: [Vercel, Mizuki]
7
category: '教程'
8
draft: false
9
---

• draft: true 表示文章为草稿，本地开发时可见，但部署上线后会被自动隐藏。

第一步：注册 Vercel 账号并关联 GitHub#

访问 Vercel 官网，使用你的 GitHub 账号直接登录。授权完成后，Vercel 便能够读取你 GitHub 账户下的所有仓库。

第二步：将代码推送至自己的 GitHub 仓库#

如果你是通过克隆方式获取的代码，需要先将远程仓库地址修改为你自己的：

1
# 查看当前远程仓库地址
2
git remote -v
3

4
# 修改为你的仓库地址（请替换为你自己的地址）
5
git remote set-url origin git@github.com:YongS998/xiaochun-blog.git
6

7
# 推送代码
8
git branch -M main
9
git push -u origin main

如果你是从源代码压缩包开始搭建的，请按照 GitHub 新建仓库页面的指引，在本地初始化 Git 并完成首次推送。

第三步：在 Vercel 中导入并部署项目#

在列表中找到并导入你刚刚推送的 GitHub 仓库。

所有构建选项保持默认，直接点击 “Deploy”。

等待一两分钟，Vercel 就会完成构建并为你生成一个 xxx.vercel.app 的预览地址。部署成功后，你应该能够通过该地址访问你的博客。不过此时在国内直接访问可能需要“特殊网络环境”。

第四步：绑定自定义域名（解决国内访问问题）#

为了让国内用户也能顺畅访问，我们需要为自己的博客绑定一个已购买的域名， 进行 DNS 解析和加速。

进入项目设置页面的 “Domains” 选项卡，输入你的自定义域名（例如 yourdomain.com）并点击添加。

此时 Vercel 会提示需要配置 DNS 解析，这是正常现象。

登录你的域名管理后台，为你的域名添加一条 CNAME 记录，将其指向 Vercel 分配给你的目标地址（格式通常为 xxxx.vercel-dns-xxx.com）。

通常几分钟后，解析便会生效。此时回到 Vercel 的 Domains 页面，域名状态应更新为绿色的“Valid”。SSL 证书也会自动签发。

一切顺利的话，你现在就可以直接使用自己的域名访问博客，并且国内访问无需任何特殊设置。