1.1 安装 Git#

1. 打开浏览器访问
   https://git-scm.com/downloads
2. 下载 Windows 版本的安装包（一般会自动识别）。
3. 双击安装，一路「Next」即可，遇到选项保持默认：
   • 编辑器选项可以保留默认的 Vim，后面我们自己用 VS Code。
   • PATH 配置选择默认那一项（推荐）。
4. 安装完成后，按下 Win + S 搜索「PowerShell」，打开一个终端，输入：

1
git --version

看到类似 git version 2.x.x 就说明安装成功。

1.2 安装 Node.js#

1. 打开 https://nodejs.org/
2. 下载推荐的 LTS 版本（绿色「LTS」按钮）。
3. 安装过程：
   • 双击安装包，勾选「I accept the terms of the License Agreement」
   • 其它选项保持默认，直到完成。
4. 安装完同样在 PowerShell 里检查：

1
node -v
2
npm -v

如果能同时看到 vXX.X.X 和 X.X.X 两行，即 Node 和 npm 都 OK。

1.3 安装 pnpm（全局）#

Fuwari 官方推荐用 pnpm 管理依赖，我们整套方案都用 pnpm。

在 管理员权限的 PowerShell 中执行：

1
npm install -g pnpm

安装完成后，验证：

1
pnpm -v

能看到一个版本号，比如 9.14.4，就说明 pnpm 安装成功。

npm 和 pnpm 的关系

• npm 是 Node 自带的包管理器
• pnpm 是第三方的高性能包管理器（节省磁盘空间）
• 我们用 npm 的唯一用途是：npm install -g pnpm，之后项目内部只用 pnpm

2.1 选择一个存放项目的目录#

我习惯把所有代码放在用户目录下，比如：C:\Users\TX。

打开 PowerShell：

1
cd C:\Users\TX

2.2 克隆 Fuwari 主题#

Fuwari 的 GitHub 仓库地址为：https://github.com/saicaca/fuwari

在 C:\Users\TX 下执行：

1
git clone https://github.com/saicaca/fuwari.git astro-blog-demo

这里我把目标文件夹命名为 astro-blog-demo，你也可以换成 blog 或任意喜欢的名字。

克隆完成后，终端会多出一段 Cloning into 'astro-blog-demo'... 的输出。

2.3 进入项目目录#

很多新手（包括我自己第一次）都会在这里踩坑： 没有 cd 进入项目目录就直接运行 npm/pnpm 命令，导致各种「找不到 package.json」。

请一定确认：

1
cd .\astro-blog-demo

此时终端提示应该变成：

1
PS C:\Users\TX\astro-blog-demo>

你可以用 dir 看看目录里是否有 package.json：

1
dir

• 顶部是 PS C:\Users\TX\astro-blog-demo>
• 下面 dir 输出中能看到 package.json 的那一行。

npm error enoent 如果你在 C:\Users\TX> 直接执行 npm install， npm 会报： Error: ENOENT: no such file or directory, open 'C:\Users\TX\package.json' 这就是没进到项目目录。

2.4 用 pnpm 安装项目依赖#

现在我们已经在项目根目录（有 package.json 的地方），执行：

1
pnpm install

这是一个关键步骤，会做这些事：

• 读取 package.json 中的 dependencies / devDependencies
• 在本地创建 node_modules，下载所有依赖
• 生成 pnpm-lock.yaml 锁定版本

注意：Fuwari 的 package.json 里有这一行：

1
"preinstall": "npx only-allow pnpm"

这表示如果你用 npm install 或 yarn，会直接报错并提示「请使用 pnpm」。 我们现在是 pnpm install，所以是正确的方式。

安装过程中可能会看到很多 WARN（弃用包、兼容性提示），只要最后没有红色的 ERROR，就说明成功。

2.5 启动本地开发服务器#

依赖安装完毕后，运行：

1
pnpm dev

稍等片刻，终端会提示类似：

1
  astro  v5.x.x ...
2

3
  Local    http://localhost:4321
4
  Network  http://192.168.xx.xx:4321

打开浏览器，访问：

1
http://localhost:4321

就能看到 Fuwari 的默认首页。

1. 终端中 pnpm dev 输出 Local http://localhost:4321 的画面；
2. 浏览器里显示 Fuwari 首页的截图（地址栏是 http://localhost:4321）。

要停止开发服务器，在终端里按下 Ctrl + C。

3.1 删除原仓库的 .git 目录#

确保当前路径还是项目根目录：

1
PS C:\Users\TX\astro-blog-demo>

执行：

1
Remove-Item -Recurse -Force .git

或简写：

1
rm -r -Force .git

删完可以用 dir -Force 看一下 .git 是否已经不在了。

3.2 初始化新的 Git 仓库#

1
git init
2
git add .
3
git commit -m "初始化 Astro + Fuwari 博客（使用 pnpm）"

4.1 在 GitHub 上新建仓库#

1. 登录 GitHub，点击右上角 + → New repository
2. Repository name 填写：astro-blog-demo（推荐与本地目录同名）
3. 其它选项保持默认，点击 Create repository

成功后会看到一个页面，上面有类似：

1
…or push an existing repository from the command line
2
git remote add origin https://github.com/你的用户名/astro-blog-demo.git
3
git branch -M main
4
git push -u origin main

4.2 本地绑定远程并推送代码#

回到 PowerShell（项目目录）：

1
cd C:\Users\TX\astro-blog-demo
2

3
git remote add origin https://github.com/你的用户名/astro-blog-demo.git
4
git branch -M main
5
git push -u origin main

⚠️ 一定要把 你的用户名 换成你真实的 GitHub 用户名。

如果一切正常，终端会显示上传进度，最后类似：

1
To https://github.com/你的用户名/astro-blog-demo.git
2
 * [new branch]      main -> main
3
Branch 'main' set up to track remote branch 'main' from 'origin'.

然后回到 GitHub 刷新仓库页面，就能看到所有项目文件。

远程地址写错 如果远程仓库没创建好，或者 URL 里还残留示例中的 你的用户名， git push 会报：remote: Repository not found. 可以用 git remote -v 检查当前绑定的 URL 是否正确。

5.1 SSH 登录 VPS#

在本地终端执行：

1
ssh root@152.53.XXX.XX

（把 IP 换成你的）

成功后提示符会变成类似 root@your-server:~#。

5.2 安装 Nginx + rsync#

1
apt update
2
apt install -y nginx rsync

5.3 创建博客文件目录#

最终静态文件放在：

1
/var/www/astro-blog-demo/dist

执行：

1
mkdir -p /var/www/astro-blog-demo/dist
2
chown -R www-data:www-data /var/www/astro-blog-demo

5.4 配置 Nginx 虚拟主机#

新建 Nginx 配置：

1
nano /etc/nginx/sites-available/astro-blog-demo.conf

写入如下内容（根据自己的域名修改 server_name）：

1
server {
2
    listen 80;
3
    server_name demo.example.com;  # 换成你的域名
4

5
    root /var/www/astro-blog-demo/dist;
6
    index index.html;
7

8
    location / {
9
        try_files $uri $uri/ /index.html;
10
    }
11
}

保存退出（nano：Ctrl + O → 回车 → Ctrl + X）。

启用站点并检查配置：

1
ln -s /etc/nginx/sites-available/astro-blog-demo.conf /etc/nginx/sites-enabled/
2
nginx -t
3
systemctl reload nginx

nginx -t 如果输出：

1
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
2
nginx: configuration file /etc/nginx/nginx.conf test is successful

就说明没问题。

5.5 配置域名 DNS（Cloudflare 示例）#

在 Cloudflare 控制台中：

1. 选择你的域名（如 xxx.top）
2. 打开「DNS → 记录」
3. 新建一条 A 记录：
   • 类型：A
   • 名称：blog
   • IPv4：152.53.XXX.XX
   • 代理状态：建议先用「仅 DNS」（灰云）

保存后等待几分钟，在本地测试：

1
ping blog.xxx.xx

能解析到服务器 IP 就表示 DNS 生效了。

6.1 在 VPS 上生成密钥对#

在 VPS 终端执行：

1
ssh-keygen -t ed25519 -C "github-actions"

一路按回车即可（路径默认 ~/.ssh/id_ed25519，密码留空）。

6.2 允许这把密钥登录#

1
cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
2
chmod 600 ~/.ssh/authorized_keys

6.3 获取私钥内容（复制到剪贴板）#

1
cat ~/.ssh/id_ed25519

完整复制 输出内容（从 -----BEGIN OPENSSH PRIVATE KEY----- 到 -----END ...-----）。 千万不要泄露给别人，这就是 Actions 登录 VPS 的凭证。

8.1 创建 Workflow 文件#

在本地项目目录中：

1
cd C:\Users\TX\astro-blog-demo
2
mkdir .github
3
mkdir .github\workflows

新建文件 .github/workflows/deploy.yml，内容如下：

1
name: Deploy blog to VPS
2

3
on:
4
  push:
5
    branches:
6
      - main   # 每次 push 到 main，就触发部署
7

8
jobs:
9
  build-and-deploy:
10
    runs-on: ubuntu-latest
11

12
    steps:
13
      - name: Checkout code
14
        uses: actions/checkout@v4
15

16
      - name: Setup Node
17
        uses: actions/setup-node@v4
18
        with:
19
          node-version: 22
20

21
      - name: Install pnpm
22
        run: npm install -g pnpm
23

24
      - name: Install dependencies
25
        run: pnpm install --frozen-lockfile
26

27
      - name: Build
28
        run: pnpm run build
29

30
      - name: Deploy via rsync over SSH
31
        env:
32
          SSH_HOST: ${{ secrets.SSH_HOST }}
33
          SSH_USER: ${{ secrets.SSH_USER }}
34
          SSH_KEY:  ${{ secrets.SSH_KEY }}
35
        run: |
36
          mkdir -p ~/.ssh
37
          echo "$SSH_KEY" > ~/.ssh/id_ed25519
38
          chmod 600 ~/.ssh/id_ed25519
39
          ssh-keyscan $SSH_HOST >> ~/.ssh/known_hosts
40

41
          rsync -avz --delete \
42
            dist/ \
43
            ${SSH_USER}@${SSH_HOST}:/var/www/astro-blog-demo/dist/

这里每一步的作用是：

1. checkout 代码
2. 安装 Node 22
3. 全局安装 pnpm
4. 用 pnpm 安装项目依赖
5. 用 pnpm 构建静态网站到 dist/
6. 用 rsync + SSH 把 dist 同步到 VPS

8.2 提交并推送 Workflow#

在 PowerShell：

1
git add .github/workflows/deploy.yml
2
git commit -m "添加 GitHub Actions 自动部署（pnpm + rsync）"
3
git push

这一次 push 会自动触发刚才创建的 Deploy blog to VPS 工作流。

打开 GitHub 仓库的 Actions 页面，可以看到一个新的 run 在执行。

如果工作流失败，可以点击进去看具体是哪个步骤报错。 常见问题：

• pnpm 没装好（忘记 Install pnpm 步骤）
• SSH_KEY 配错（复制不完整）
• Nginx 目录路径不一致（rsync 同步到的路径和 Nginx root 不一致）

9.1 新建一篇文章#

以 Fuwari 的内容目录结构为准（例如 src/content/posts）， 新建一个文件 src/content/posts/hello-fuwari.md：

1
---
2
title: Hello Fuwari
3
published: 2025-12-08
4
description: ''
5
image: ''
6
tags: []
7
category: ''
8
draft: false
9
lang: ''
10
---
11

12
这是我用 Fuwari + pnpm 重建博客后的第一篇测试文章。

9.2 本地预览确认文章正常#

在项目目录中运行：

1
pnpm dev

然后打开 http://localhost:4321，看首页是否已经出现新文章。 确认没问题后，按 Ctrl + C 停掉 dev。

9.3 提交并推送#

1
git add src/content/posts/hello-fuwari.md
2
git commit -m "发布第一篇文章：Hello Fuwari"
3
git push

GitHub Actions 会自动运行一次 Deploy blog to VPS 工作流。

等待所有步骤变成绿色对勾。

9.4 访问正式域名#

浏览器访问：

1
http://blog.XXX.XXX

或（配置好 HTTPS 之后）：

1
https://blog.XXX.XXX

能看到首页已经更新，并且可以点击进入《Hello Fuwari》这篇文章，就说明博客已顺利部署完成 ✅。