第零步：准备工作#

我们需要安装Git，Nodejs，以及准备一个GitHub账号，并且创建一个自己的仓库用于存放我们的代码，这样我们的博客便托管在GitHub上（甚至服务器都借用的GitHub的不用自己掏钱了XD）。

• 安装Git
  
• 安装Node.js（版本需>=22）
  
• 创建一个GitHub账户
  
• 在GitHub网页新建一个Github仓库，不是从Github Desktop新建一个本地仓库！
  可将仓库命名为<用户名>.github.io
  
• （可选）安装GitHub Desktop
  

如果使用GitBash执行指令push，pull，clone时出现类似这样的报错：

1
Failed to connect to github.com port 443 after 21052 ms: Could not connect to server

大概率是Git的代理配置出了问题，可以用更改代理的方法解决，但是另一个更简单快捷的方法是使用 GitHub Desktop，GitHub Desktop会自动配制好我们的网路，而且图形化的操作窗口更加简单，适合新手使用。
GitHub Desktop使用参考
安装完成后，可以Win+R调出cmd输入以下指令查看git和nodejs是否正确安装。

1
git -v
2
node -v
3
npm -v

然后在cmd中输入以下指令安装pnpm：

1
npm install -g pnpm

安装完成后，需要重启电脑保证成功部署。

第一步：clone仓库到本地#

在本地任意位置新建文件夹（可命名为git），然后右键并选择 “Open Git Bash here”，在窗口里输入指令：

1
git init

顺带一提git里面粘贴是Shift+Insert而不是Ctrl+V，同样地复制是Ctrl+Insert而不是Ctrl+C。
之后这个文件夹就成为了你本地的git仓库。
然后将Mizuki仓库clone到本地。

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

若出现443报错可安装Github Desktop解决
此时Mizuki的仓库就已经clone到本地了，不过，在更改它的文件之前，我们还要先删除原来的.git信息，否则.git里面包含的提交url仍然是https://github.com/LyraVoid/Mizuki.git，进而导致我们之后push的时候就会默认push到Mizuki的仓库而不是我们自己的仓库导致访问被拒绝。
具体地，按照以下步骤进行操作：

1. 进入Mizuki目录：
   

1
cd Mizuki

2. 删除原有的git信息：
   

1
rm -rf .git

3. 重新初始化：
   

1
git init
2
git add .
3
git commit -m "Initial commit"

4. 再连接到自己的Github仓库：
   

1
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
2
git branch -M main

现在这个仓库就完全属于我们自己了，后续的改动也不会受到原仓库的影响。

20260718补：若使用GitHub Desktop，按照以下步骤进行：

1. 打开GitHub Desktop，从左上角File下拉菜单中选择Clone repository，在弹出的窗口中选择URL，在第一栏输入https://github.com/LyraVoid/Mizuki，第二栏选择你希望将文件放在的位置；
2. 找到下载的文件的文件夹，右键此文件夹（Mizuki），选择 “Open Git Bash here”，然后后从上面的第二步继续操作。

第二步：○○，启动！#

使用pnpm安装项目依赖：

1
pnpm install

可以用pnpm -v检查是否安装完毕，随后执行指令

1
pnpm dev

稍等片刻后，便可看到本地开发服务器成功启动，从返回的信息中可以看到服务器已经成功在本地http://localhost:3000/启动（实际上官方文档里写的是http://localhost:4321/），将其复制后粘贴进浏览器即可看见本地启动的网站。（不要关闭GitBash窗口！！！）

第三步：配置你的网页#

参考Mizuki主题的官网文档进行配置。
更改本地仓库的文件后进行保存，浏览器中的网页会自动刷新，即刻展示修改内容（文章修改可能会卡一会）。
配置完后可以在Mizuki目录中使用以下指令检测是否有报错，确保网站上传后能正常运行。

1
pnpm build

在build成功之后，可以使用以下指令预览网站的实际样式，同样地，从返回信息中的http://localhost:3000/访问本地的网站：

1
pnpm preview

• tips1：官网文档里“基础布局”和“文章布局”栏目中包含的src/config.ts文件，实际上指的是src\config文件夹，siteConfig对象指的是这个文件夹中的文件siteConfig.ts，其他同理。此外，“文章布局”栏目中toc对象放在文件siteConfig.ts之中。(好乱啊wwwww)
  
• tips2：如果需要更改界面文字，可以到\src\i18n\languages\zh_CN.ts中更改。
  
• 补：build阶段若出现以下的报错：
  

1
16:36:51 [ERROR] [vite] ✗ Build failed in 3.93s
2
WebAssembly.Memory.grow(): Maximum memory size exceeded

有可能是修改了\src\data\skills.ts导致的。
初步判断在skills.ts中simple-icons:nginx、simple-icons:firebase、simple-icons:sqlite、simple-icons:express这四个icon的文本需要有至少一个文本被包含在文件中，才能正常运行。
解决方式：在文件skills.ts开头加上以下的注释。（这很诡异你知道吗）

1
// "simple-icons:sqlite"

第四步：提交到GitHub#

在网页GitHub的仓库里打开 Settings ,在其中找到 Pages ，将Build and deployment 中的 Deploy from a branch 更改为 Github Actions。
然后打开\.github\workflow\deploy.yaml，将其替换为以下代码：

1
name: Deploy to GitHub Pages
2
on:
3
  # 每次推送到 `main` 分支时触发这个“工作流程”
4
  # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
5
  push:
6
    branches: [ main ]
7
  # 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
8
  workflow_dispatch:
9
# 允许 job 克隆 repo 并创建一个 page deployment
10
permissions:
11
  contents: read
12
  pages: write
13
  id-token: write
14
jobs:
15
  build:
16
    runs-on: ubuntu-latest
17
    steps:
18
      - name: Checkout your repository using git
19
        uses: actions/checkout@v4
20
      - name: Install, build, and upload your site
21
        uses: withastro/action@v3
22
        with:
23
          # path: . # 存储库中 Astro 项目的根位置。（可选）
24
          node-version: 22 # 用于构建站点的特定 Node.js 版本，默认为 20。（可选）
25
          # package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。（可选）
26
  deploy:
27
    needs: build
28
    runs-on: ubuntu-latest
29
    environment:
30
      name: github-pages
31
      url: ${{ steps.deployment.outputs.page_url }}
32
    steps:
33
      - name: Deploy to GitHub Pages
34
        id: deployment
35
        uses: actions/deploy-pages@v4

官网文档中的代码node-version默认是20，但是实际上构建这个网站需要node-version至少22.13，这会导致GitHubActions的build过程中报错，因此我在此处直接将其改为22。
运行以下指令，将你的网页代码提交到GitHub仓库中。

1
git add .
2
git commit -m "Summary message"
3
git push

若出现443报错可安装Github Desktop解决
提交完成之后，GitHub便会自动帮助我们build和deploy网站。
build和deploy都成功后，我们便可以到<用户名>.github.io上去访问自己的个人网站啦。
后续维护时，也只需执行以上三段指令，即可将本地的进度同步到GitHub Pages。
20260718补：使用GitHub Desktop进行提交时，按照以下步骤操作：

1. 修改完文件后，点击左下角蓝色按钮 “Commit xxx files to main”；
   
2. 点击右侧蓝色按钮 “Push origin”。
   

后记#