先弄清楚整个流程#

Fuwari 是一个基于 Astro 的静态博客模板。我们写 Markdown，Astro 把它构建成网页，GitHub 保存源文件，Vercel 读取 GitHub 的 main 分支并自动发布。

完整链路是：

1
在本地修改文件
2
→ 本地开发服务器预览
3
→ 检查并生产构建
4
→ Git 工作分支提交
5
→ 合并进 main
6
→ 推送 main 到 GitHub
7
→ Vercel 自动构建
8
→ 打开正式网址验证

其中最容易混淆的一点是：保存本地文件并不会更新网站，commit 也不会。只有 GitHub 上与 Vercel 连接的生产分支更新后，Vercel 才能收到新版本。

一、准备工具#

需要安装：

• Git：保存版本并连接 GitHub；
• Node.js 22 LTS：运行 Astro；
• pnpm 9：安装依赖和执行项目命令；
• VS Code：编辑代码和 Markdown。

安装后新开 PowerShell，逐行执行：

1
git --version
2
node --version
3
pnpm --version

每条命令都应该输出版本号。若提示“不是内部或外部命令”，先关闭并重开终端，让新的环境变量生效。

二、从模板创建自己的 GitHub 仓库#

1. 打开 Fuwari 仓库；
2. 点击 Use this template → Create a new repository；
3. Owner 选自己的 GitHub 账号；
4. Repository name 填 my-blog；
5. 创建仓库。

推荐使用模板，而不是直接 Fork。模板会生成一个更像“自己的新项目”的仓库；Fork 更适合持续向原项目贡献代码，但会保留明显的上下游关系。

三、明确目录和克隆位置#

外层收纳目录是：

1
D:\AAA_Ai-Code\project-005-WebBlog

它可以通过 PowerShell 创建，也可以在资源管理器中手动创建，两种结果完全一样。PowerShell 做法：

1
New-Item -ItemType Directory -Force D:\AAA_Ai-Code\project-005-WebBlog
2
Set-Location D:\AAA_Ai-Code\project-005-WebBlog
3
Get-Location

这三行分别是创建目录、进入目录、确认当前目录。接着克隆：

1
git clone https://github.com/azlove2021/my-blog.git
2
Set-Location .\my-blog
3
git rev-parse --show-toplevel

git clone 会在当前目录自动新建 my-blog，因此最终项目地址是：

1
D:\AAA_Ai-Code\project-005-WebBlog\my-blog

Set-Location .\my-blog 必须在克隆成功后执行；它表示进入刚创建的子目录。以后每次新开终端，也先执行：

1
Set-Location D:\AAA_Ai-Code\project-005-WebBlog\my-blog

1
Recv failure: Connection was reset
2
Failed to connect to github.com port 443

1
git config --global http.https://github.com.proxy http://127.0.0.1:7897
2
git config --global --get http.https://github.com.proxy
3
git ls-remote https://github.com/azlove2021/my-blog.git HEAD

1
git config --global --unset http.https://github.com.proxy

四、安装依赖并本地运行#

确认提示符位于项目根目录，然后执行：

1
pnpm install --frozen-lockfile
2
pnpm dev

浏览器打开终端显示的地址，通常是 http://localhost:4321/。pnpm dev 会持续运行；结束时按 Ctrl + C。

为什么用 --frozen-lockfile：它严格按照仓库中的 pnpm-lock.yaml 安装，避免第一次安装就擅自升级依赖。普通 pnpm install 更灵活，但可能改写锁文件。

五、创建工作分支#

先同步正式分支，再创建一条独立修改线：

1
git switch main
2
git pull --ff-only
3
git status
4
git switch -c feature/setup-my-blog
5
git branch --show-current

最后应该输出 feature/setup-my-blog。分支名可以换成描述本次任务的英文短语。

分支的优点是修改失败时不立刻污染正式版本，也便于在 GitHub 查看差异；直接改 main 少几步，但每次推送都可能马上触发生产部署。

六、修改博客配置#

主要配置在 src/config.ts。修改标题、副标题、导航、头像等信息时，先保持字段结构不变，只改字符串值。

本项目的语言代码应使用：

1
lang: "zh_CN"

不要写成 zh-CN。两者看起来接近，但 Fuwari 的类型定义使用下划线版本，写错会让 pnpm check 报错。

部署地址在 astro.config.mjs：

1
site: "https://my-blog-xi-gilt.vercel.app/",
2
base: "/",

Vercel 站点部署在域名根目录，因此 base 保持 /。如果改用 GitHub Pages 的项目仓库地址，base 往往要改成 /my-blog/，不能直接照搬。

七、写文章与封面#

推荐一篇文章一个文件夹：

1
src/content/posts/my-blog/
2
├── index.md
3
└── cover.jpeg

index.md 的开头称为 Frontmatter：

1
---
2
title: 从 Fuwari 到 Vercel：小白搭建个人博客完整记录
3
published: 2026-06-21
4
description: 一步一步搭建并发布自己的 Fuwari 博客。
5
image: "./cover.jpeg"
6
tags: [Fuwari, Astro, GitHub, Vercel]
7
category: 建站教程
8
draft: false
9
lang: "zh_CN"
10
---

封面与 index.md 相邻，所以写 ./cover.jpeg。文件名大小写必须一致；Windows 本地可能不敏感，Linux 构建环境通常敏感。

draft: true 表示草稿，生产构建不会发布；准备上线时改为 false。

八、把演示文章隐藏但保留下来#

不要把演示文章移入 src/content/posts/temp，因为它仍位于 Astro 的内容目录，可能继续被扫描。

推荐在项目根目录保存：

1
temp/posts/

例如：

1
New-Item -ItemType Directory -Force .\temp\posts
2
Move-Item .\src\content\posts\markdown.md .\temp\posts\
3
Move-Item .\src\content\posts\guide .\temp\posts\

文章文件夹要整体移动，避免正文与图片分离。恢复时反向执行：

1
Move-Item .\temp\posts\markdown.md .\src\content\posts\

这种方式比永久删除更适合第一次建站：页面干净了，示例写法仍能从 temp/posts 找回，而且 Git 会保存这些文件。

九、本地调试和上线前门禁#

边写边看：

1
pnpm dev

准备发布时按 Ctrl + C 停止开发服务器，然后依次执行：

1
pnpm check
2
pnpm type-check
3
pnpm build
4
pnpm preview

四者职责不同：

• check：检查 Astro、Svelte 与内容类型；
• type-check：检查 TypeScript；
• build：真正生成生产网站，是最重要的上线门槛；
• preview：用生产构建结果启动本地网站，发现只在构建后出现的问题。

不能只看首页能打开，还要检查文章页、封面、导航、深色模式、手机宽度和外链。dev 正常不等于生产构建一定正常。

十、检查、提交和合并#

先看改了什么：

1
git status
2
git diff

确认没有密码、API Key、.env、私人照片或不认识的文件，再提交：

1
git add .
2
git status
3
git diff --cached
4
git commit -m "Publish Fuwari setup tutorial"

git add 是选择下一次快照，git commit 是在本地制作版本快照。两者都没有把文件发到 GitHub。

1
git push -u origin feature/setup-my-blog

1
git switch main
2
git pull --ff-only

1
git switch main
2
git pull --ff-only
3
git merge --no-ff feature/setup-my-blog
4
git push origin main

十一、Vercel 自动部署到底怎样工作#

第一次部署：

1. 使用 GitHub 登录 Vercel；
2. 点击 Add New → Project；
3. 导入 azlove2021/my-blog；
4. Framework Preset 选择或自动识别 Astro；
5. Production Branch 设为 main；
6. 点击 Deploy。

仓库连接完成后：

• 推送工作分支通常生成 Preview Deployment；
• PR 合并到 main，或执行 git push origin main，会触发 Production Deployment；
• Vercel 状态为 Building 时继续等待；
• 状态为 Ready 后，正式网址才应该出现新内容；
• 状态为 Error 时查看构建日志，修复后重新提交，不要只反复点 Redeploy。

上线验证不能只检查 HTTP 200，因为旧版本也会返回 200。应打开新文章地址，确认能看到这篇文章的独特标题，同时确认演示文章已经不再显示。

十二、以后每次发文章的固定流程#

1
Set-Location D:\AAA_Ai-Code\project-005-WebBlog\my-blog
2
git switch main
3
git pull --ff-only
4
git switch -c post-new-article
5
pnpm new-post new-article
6
pnpm dev

写完后：

1
pnpm check
2
pnpm type-check
3
pnpm build
4
git status
5
git diff
6
git add .
7
git diff --cached
8
git commit -m "Add article: 文章标题"
9
git push -u origin post-new-article

在 GitHub 合并 PR，再执行：

1
git switch main
2
git pull --ff-only
3
git branch -d post-new-article

只有确认合并完成后才删除本地工作分支。普通写文章没有修改依赖，不必每次运行 pnpm install。

十三、上线出错如何回滚#

先查看最近提交：

1
git log --oneline -5

如果错误提交已经推送到 GitHub，优先创建一个撤销提交：

1
git revert <需要撤销的提交哈希>
2
git push origin main

git revert 会保留完整历史，Vercel 也会根据新的 main 自动重新部署。不要把 git reset --hard 当作线上回滚按钮，它可能直接丢弃本地修改并改写历史。

最后的完成标准#

一次发布只有同时满足以下条件才算完成：

• pnpm check、pnpm type-check、pnpm build 全部成功；
• GitHub 的 main 包含目标 commit；
• Vercel 对应部署状态是 Ready；
• 正式首页和新文章地址可以打开；
• 新标题和封面真实出现；
• 被移走的演示文章不再显示。

当这条链路第一次完整跑通，以后发文章就不再是一场玄学仪式，而是一套可以重复、可以检查、也可以回退的小流程。