Mizuki博客部署与配置指南：从零搭建个人技术博客

一、Mizuki 简介

Mizuki 是一个基于 Astro 框架的现代化博客主题，具有以下特点：

• 高性能：静态生成，加载速度快
• 美观设计：现代化UI，支持暗色模式
• 功能丰富：支持文章分类、标签、搜索、评论等
• 易于配置：通过配置文件即可自定义

1.1 技术栈

二、环境准备

2.1 系统要求

• Node.js: >= 22
• pnpm: >= 9
• 操作系统: Windows/macOS/Linux

2.2 安装 Node.js

# Windows (使用 nvm-windows)
# 下载安装 https://github.com/coreybutler/nvm-windows/releases
macOS/Linux (使用 nvm)#
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

2.3 安装 pnpm

npm install -g pnpm
pnpm --version  # 验证安装

三、项目部署

3.1 获取源码

# 克隆仓库
git clone https://github.com/LyraVoid/Mizuki.git
cd Mizuki
或者下载压缩包解压#

3.2 安装依赖

pnpm install

3.3 配置博客

编辑 src/config.ts 文件：

export const siteConfig: SiteConfig = {
    title: "你的博客名称",
    subtitle: "你的博客副标题",
    siteURL: "https://your-domain.com/",
    siteStartDate: "2024-01-01",
    lang: "zh_CN",
    // ... 其他配置
};
export const profileConfig: ProfileConfig = {
avatar: “assets/images/avatar.webp”,
name: “你的名字”,
bio: “你的个人简介”,
links: [
{
name: “GitHub”,
icon: “fa7-brands
Invalid repository. ("repo" attributte must be in the format "owner/repo")
”,
url: “https://github.com/your-username”,
},
],
};

3.4 构建项目

pnpm build

构建产物在 dist/ 目录。

四、服务器部署

4.1 使用 Nginx

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/blog/dist;
    index index.html;
1
# 支持前端路由
2
location / {
3
    try_files $uri $uri/ $uri/index.html =404;
4
}
5

6
# 静态资源缓存
7
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff2)$ {
8
    expires 1y;
9
    add_header Cache-Control "public, immutable";
10
}
11

12
# 安全头
13
add_header X-Frame-Options "SAMEORIGIN" always;
14
add_header X-Content-Type-Options "nosniff" always;
15
add_header X-XSS-Protection "1; mode=block" always;
}

4.2 使用 Docker

FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install
COPY . .
RUN pnpm build
FROM nginx
COPY —from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

docker build -t blog .
docker run -d -p 80\:80 blog

五、文章编写#

5.1 文章目录#

所有文章放在 src/content/posts/ 目录下：

1
src/content/posts/
2
├── my-first-post.md
3
├── another-post.md
4
└── ...

5.2 Frontmatter 格式#

1
---
2
title: "文章标题"
3
published: 2024-01-01
4
description: "文章简介"
5
image: "./cover.jpg"
6
tags: ["标签1", "标签2"]
7
category: "博客搭建"
8
draft: false
9
pinned: false
10
lang: "zh_CN"
11
---

5.3 Markdown 语法#

Mizuki 支持标准 Markdown 语法，以及以下扩展：

代码块：

1
print("Hello, World!")

Callouts：

[!NOTE] 这是一个提示框

[!WARNING] 这是一个警告框

数学公式： $$ E = mc^2 $$

GitHub 卡片： ::github{repo="LyraVoid/Mizuki"}

六、自定义配置#

6.1 导航栏配置#

在 src/config.ts 中配置 navBarConfig：

1
export const navBarConfig: NavBarConfig = {
2
    links: [
3
        LinkPreset.Home,
4
        LinkPreset.Archive,
5
        {
6
            name: "知识库",
7
            url: "/content/",
8
            children: [
9
                { name: "Web安全", url: "/posts/category/web-security/" },
10
                { name: "渗透测试", url: "/posts/category/pentest/" },
11
            ],
12
        },
13
    ],
14
};

6.2 技能页面配置#

编辑 src/data/skills.ts：

1
export const skillsData: Skill[] = [
2
    {
3
        id: "python",
4
        name: "Python",
5
        description: "脚本开发、自动化工具",
6
        icon: "logos:python",
7
        category: "博客搭建",
8
        level: "advanced",
9
        experience: { years: 2, months: 0 },
10
        color: "#3776AB",
11
    },
12
    // ... 更多技能
13
];

6.3 友链配置#

编辑 src/data/friends.ts：

1
export const friendsData: FriendItem[] = [
2
    {
3
        id: "friend1",
4
        title: "朋友的博客",
5
        imgurl: "https://example.com/avatar.jpg",
6
        desc: "一个很棒的技术博客",
7
        siteurl: "https://friend-blog.com",
8
        tags: ["技术", "安全"],
9
    },
10
];

七、常见问题#

7.1 构建失败#

问题：pnpm build 报错

解决：

1
# 清除缓存
2
rm -rf node_modules .astro dist
3
pnpm install
4
pnpm build

7.2 文章不显示#

检查：

1. draft 是否为 false
2. published 日期是否正确
3. 文件名是否正确

7.3 搜索不工作#

解决：确保构建时生成了 Pagefind 索引：

1
pnpm build  # 会自动运行 pagefind

7.4 图片不显示#

解决：

• 图片放在 public/ 目录
• 使用 / 开头的绝对路径
• 或使用相对路径（相对于文章文件）

八、SEO 优化#

8.1 站点地图#

Mizuki 自动生成 sitemap.xml，确保在 robots.txt 中引用：

1
Sitemap: https://your-domain.com/sitemap.xml

8.2 RSS 订阅#

访问 /rss.xml 或 /atom.xml 获取订阅链接。

8.3 Meta 标签#

在 src/config.ts 中配置：

1
export const siteConfig: SiteConfig = {
2
    // ... 其他配置
3
    lang: "zh_CN",
4
};

九、总结#

9.1 部署清单#

• [ ] 安装 Node.js 和 pnpm
• [ ] 克隆项目并安装依赖
• [ ] 配置 src/config.ts
• [ ] 编写文章
• [ ] 构建项目
• [ ] 部署到服务器
• [ ] 配置域名和 SSL

9.2 维护建议#

1. 定期更新依赖
2. 备份源码和配置
3. 监控网站性能
4. 及时修复安全漏洞

参考资料：

• Mizuki 官方文档
• Astro 官方文档
• Tailwind CSS 文档

声明：本文基于 Mizuki 项目编写，项目地址：https://github.com/LyraVoid/Mizuki