mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
625 字
2 分钟
Mizuki博客部署与配置指南:从零搭建个人技术博客
2026-06-09

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

一、Mizuki 简介#

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

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

1.1 技术栈#

技术版本用途
Astro6.x静态站点生成
Svelte5.xUI组件
Tailwind CSS4.x样式框架
TypeScript5.x类型安全
Pagefind1.x搜索功能

二、环境准备#

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:github",
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;
# 支持前端路由
location / {
try_files $uri $uri/ $uri/index.html =404;
}
# 静态资源缓存
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# 安全头
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
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:alpine
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/ 目录下:

src/content/posts/
├── my-first-post.md
├── another-post.md
└── ...

5.2 Frontmatter 格式#

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

5.3 Markdown 语法#

Mizuki 支持标准 Markdown 语法,以及以下扩展:

代码块

print("Hello, World!")

Callouts

NOTE

这是一个提示框

WARNING

这是一个警告框

数学公式

E=mc2E = mc^2

GitHub 卡片

LyraVoid
/
Mizuki
Waiting for api.github.com...
00K
0K
0K
Waiting...

六、自定义配置#

6.1 导航栏配置#

src/config.ts 中配置 navBarConfig

export const navBarConfig: NavBarConfig = {
links: [
LinkPreset.Home,
LinkPreset.Archive,
{
name: "知识库",
url: "/content/",
children: [
{ name: "Web安全", url: "/posts/category/web-security/" },
{ name: "渗透测试", url: "/posts/category/pentest/" },
],
},
],
};

6.2 技能页面配置#

编辑 src/data/skills.ts

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

6.3 友链配置#

编辑 src/data/friends.ts

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

七、常见问题#

7.1 构建失败#

问题pnpm build 报错

解决

# 清除缓存
rm -rf node_modules .astro dist
pnpm install
pnpm build

7.2 文章不显示#

检查

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

7.3 搜索不工作#

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

pnpm build # 会自动运行 pagefind

7.4 图片不显示#

解决

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

八、SEO 优化#

8.1 站点地图#

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

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

8.2 RSS 订阅#

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

8.3 Meta 标签#

src/config.ts 中配置:

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

九、总结#

9.1 部署清单#

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

9.2 维护建议#

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

参考资料

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

分享

如果这篇文章对你有帮助,欢迎分享给更多人!

Mizuki博客部署与配置指南:从零搭建个人技术博客
https://lansame.top/posts/mizuki-blog-deploy-guide/
作者
Lansame
发布于
2026-06-09
许可协议
CC BY-NC-SA 4.0

部分信息可能已经过时

目录