千岛の摸鱼小栈

必备工具#

• Git：用于克隆项目代码、推送代码到远程仓库

• 远程仓库：推荐 GitHub（国际版）/ Gitee（国内版），用于存储博客代码

• 代码编辑器：推荐 VS Code，轻量且功能强大，编辑代码/配置更方便

环境要求#

• Node.js ≥ 20

• pnpm ≥ 9

• Git

1. 安装 Node.js#

1. 访问 Node.js 官网，优先下载「LTS 版本」（长期支持版，更稳定，适合生产环境）；

2. 双击安装包，按默认选项下一步即可（Windows 建议勾选「Add to PATH」，自动配置环境变量）；

3. 验证安装：打开终端（Windows 按 Win+R 输 cmd，Mac 按 Command+空格 输 Terminal），执行以下命令：

1
# 查看 Node.js 版本
2
node -v
3
# 查看 npm 版本
4
npm -v

4. 若终端显示「v20.x.x」（或更高版本），则安装成功。

2. 安装 pnpm#

pnpm 是 Astro 推荐的包管理器，通过 npm 即可快速安装：

1
npm install -g pnpm  # -g 表示全局安装，所有项目都能使用

验证安装：终端执行以下命令，显示「9.x.x」（或更高版本）即成功：

1
pnpm -v

3. 安装 Git#

1. 访问 Git 官网，根据自己的操作系统（Windows/Mac/Linux）下载对应安装包；

2. 双击安装，按默认选项下一步即可（Windows 建议勾选「Add Git to PATH」）；

3. 验证安装：终端执行以下命令，显示 Git 版本号即成功：

1
git --version

1. 克隆 Mizuki 项目#

先获取主题代码，有两种方式，选一种即可（克隆慢选方式二）：

1
# 方式一：Git 克隆（推荐，后续推送代码更方便）
2
git clone https://github.com/matsuzaka-yuki/Mizuki
3

4
# 方式二：直接下载压缩包（克隆慢/网络差时用）
5
# 1. 访问 https://github.com/matsuzaka-yuki/Mizuki
6
# 2. 点击右上角「Code」→「Download ZIP」
7
# 3. 解压压缩包到你想存放的文件夹

2. 用 VS Code 打开项目#

1. 打开 VS Code，点击「文件」→「打开文件夹」，选择刚才克隆/解压的「Mizuki」文件夹；

2. 打开 VS Code 终端：点击顶部菜单栏「终端」→「新建终端」；

3. 确认终端路径：终端左侧显示「Mizuki」即当前路径正确；若路径不对，执行以下命令切换（替换为你的实际路径）：

1
# 示例：Windows 路径
2
cd C:\你的文件夹路径\Mizuki
3

4
# 示例：Mac 路径
5
cd /Users/你的用户名/你的文件夹路径/Mizuki

3. 安装依赖 & 启动本地博客#

在 VS Code 终端中执行以下命令，安装项目所需依赖：

1
pnpm install

⚠️ 注意：安装依赖时若出现报错，大概率是 Node.js 版本过低，确认版本 ≥20 即可。

依赖安装完成后，启动本地服务预览博客：

1
pnpm dev  # 启动开发服务器

启动成功后，终端会显示访问地址（通常是 http://localhost:4321），复制地址到浏览器打开，就能看到你的本地博客啦～

4. 个性化配置博客#

修改配置文件，让博客变成你的专属风格，核心配置文件为 src/config.ts（VS Code 左侧文件树中找到该文件，双击打开）。

以下是常用配置项说明（按注释修改即可，无需懂代码）：

1
// src/config.ts 核心配置示例（保留原文件结构，修改对应值即可）
2
export default {
3
  siteConfig: {
4
    title: "我的个人博客",       // 博客标题（浏览器标签页显示）
5
    subtitle: "记录技术与生活",   // 博客副标题（首页顶部显示）
6
    const SITE_LANG = "zh_CN"; // 语言代码，例如：'en', 'zh_CN', 'ja' 等。
7
  const SITE_TIMEZONE = 8; //设置你的网站时区 from -12 to 12 default in UTC+8
8
    avatar: "你的头像文件夹路径",        // 头像（将图片放入指定文件夹，填写文件名即可）
9
    links: {                     // 社交链接（头像底部显示）
10
      GitHub: "https://github.com/你的用户名",
11
      知乎: "https://www.zhihu.com/people/你的用户名",
12
      微博: "https://weibo.com/你的用户名"
13
    }
14
  },
15
    featurePages: {
16
        anime: boolean; // 番剧页面开关
17
        diary: boolean; // 日记页面开关
18
        friends: boolean; // 友链页面开关
19
        projects: boolean; // 项目页面开关
20
        skills: boolean; // 技能页面开关
21
        timeline: boolean; // 时间线页面开关
22
        albums: boolean; // 相册页面开关
23
        devices: boolean; // 设备页面开关
24
    };
25
  // 其他配置可参考文件内注释，按需修改
26
}

修改完成后，保存文件，浏览器会自动刷新，实时看到修改效果～

1. 准备 GitHub 仓库（存储代码）#

1. 登录 GitHub 账号（没有账号的话，注册一个，免费）；

2. 点击右上角「+」→「New repository」（新建仓库）；

3. 填写仓库信息：

   1. Repository name：仓库名称（如 mizuki-blog，自定义即可）；

   2. Visibility：选择「Private」（私有仓库，防止敏感信息泄漏）；

   3. 勾选「Add a README file」（可选，方便后续管理）；

4. 点击「Create repository」，完成仓库创建；

5. 将本地博客代码推送到 GitHub 仓库（VS Code 终端执行以下命令，替换为你的仓库地址）：

1
# 1. 初始化 Git 仓库（若已用 git clone 克隆项目，可跳过此步）
2
git init
3

4
# 2. 将所有文件添加到暂存区
5
git add .
6

7
# 3. 提交文件（注释可自定义，如「初始化博客」）
8
git commit -m "init mizuki blog"
9

10
# 4. 关联 GitHub 仓库（替换为你的仓库地址，复制仓库页面的「HTTPS」地址）
11
git remote add origin https://github.com/你的用户名/你的仓库名.git
12

13
# 5. 推送代码到 GitHub（首次推送可能需要登录 GitHub 验证）
14
git push -u origin main

推送成功后，刷新 GitHub 仓库页面，能看到 Mizuki 项目的所有文件，即完成代码同步。

2. 配置 EdgeOne Pages（部署代码）#

我们使用腾讯云 EdgeOne 国际版（免费额度足够个人博客使用），步骤如下：

1. 登录 腾讯云 EdgeOne 控制台（没有账号的话，注册并完成实名认证，免费）；

2. 顶部搜索框输入「EdgeOne」，点击进入 EdgeOne 产品页面；

3. 左侧导航栏找到「EdgeOne Pages」→「项目管理」，点击「新建应用」；

3. 连接 GitHub 仓库#

1. 代码源选择「GitHub」，点击「去授权」；

2. 跳转到 GitHub 授权页面，勾选「允许访问你的仓库」，点击「Authorize」完成授权；

3. 返回 EdgeOne 页面，从下拉列表中选择你刚才创建的 GitHub 仓库（如 mizuki-blog）；

4. 选择部署分支：默认「main」（若仓库分支是 master，选择 master 即可）。

4. 构建设置（关键！必须配置正确）#

这一步决定部署是否成功，按以下配置填写，不要出错：

• 框架预设：选择「Astro」（若没有，选择「静态网站」）；

• 构建命令：填写 pnpm install && pnpm build（先安装依赖，再构建项目）；

• 输出目录：填写 dist（Astro 构建后的文件目录，固定值）；

• Node.js 版本：选择「20.x」或更高版本（匹配本地 Node.js 版本）；

填写完成后，点击「部署」，EdgeOne 会自动执行构建流程（约 1-3 分钟）。

⚠️ 注意：构建成功后，EdgeOne 会生成一个「预览网址」，该网址仅有效 3 小时，且需要 token 验证，仅用于测试，后续需配置自己的域名。

1. 购买域名（低成本）#

推荐在阿里云购买，新手有一元域名活动（.top/.xyz 等后缀），步骤如下：

1. 访问 阿里云域名注册，登录账号；

2. 搜索你想要的域名（如 yourname.top），选择心仪的后缀，加入购物车；

3. 结算时，填写「域名信息模板」（需完成实名认证，上传身份证照片，审核约 1-2 小时）；

4. 支付成功后，等待域名审核通过（审核通过后，域名才能正常使用）。

2. EdgeOne 配置自定义域名#

1. 进入 EdgeOne Pages 项目控制台，点击「域名设置」→「添加自定义域名」；

2. 输入你的域名（推荐用二级域名，如 blog.yourdomain.com），点击「下一步」；

3. 获取 DNS 解析记录：EdgeOne 会生成两条解析记录（CNAME 类型），复制记录值；

4. 配置阿里云 DNS 解析：

   1. 打开 阿里云 DNS 控制台，找到你购买的域名；

   2. 点击「解析设置」→「添加记录」；

   3. 按 EdgeOne 提示填写：

   4. 点击「确认」，完成解析添加。

5. 返回 EdgeOne 页面，点击「验证」，等待 DNS 解析生效（约 10-30 分钟）；

6. 解析生效后，EdgeOne 会自动颁发 SSL 证书（免费），开启 HTTPS 加密（浏览器显示小绿锁）。

1. 克隆项目慢/失败？#

解决方案：用 Gitee 镜像克隆（复制 Mizuki 仓库到 Gitee，再克隆 Gitee 仓库），或直接下载 ZIP 压缩包。

2. 安装依赖报错？#

原因：Node.js 版本过低（<20）或网络问题。

解决方案：升级 Node.js 到 20+ 版本；换国内镜像源：pnpm config set registry https://registry.npmmirror.com，再重新安装依赖。

3. 部署构建失败？#

检查两点：① 构建设置是否正确（命令、输出目录、Node 版本，pnpm环境）；② GitHub 仓库是否同步了所有本地文件。

4. 域名解析不生效？#

解决方案：等待 30 分钟（DNS 解析需要时间）；检查阿里云解析记录是否填写正确（主机记录、记录值、类型）；清除浏览器缓存后测试。