从零到上线：个人博客搭建完整记录

前言#

作为一名编程新手，我一直想拥有自己的个人博客。今天（2026年2月8日），在 Claude Code（AI 编程助手） 的帮助下，我从零开始完成了个人博客的搭建，并成功部署到了 Cloudflare Pages。

这篇文章详细记录了完整的搭建过程，包括遇到的困难、解决方案以及最终的成功部署。希望能帮助到同样想建站的新手朋友们。

为什么选择静态博客？#

在开始之前，我对比了几种主流的博客方案：

方案对比#

1. 动态博客系统（Halo）#

优点：功能完整、有管理后台
缺点：需要服务器、配置复杂、成本高
适合：需要复杂功能、有服务器经验的人

2. 前后端分离（React/Vue + 后端）#

优点：完全自定义
缺点：开发工作量大
适合：全栈开发者

3. 静态博客（Astro + Vercel/Cloudflare Pages）#

优点：
- 本地 Markdown 写作
- Git 推送自动部署
- 完全免费托管
- 性能极佳
- 安全可靠
缺点：需要学习一点 Git
适合：新手和想要简单博客的人

最终选择#

我选择了 Astro + Cloudflare Pages 方案，主要因为：

Claude Code 推荐，适合新手
自动部署，不需要手动操作
完全免费
国内访问速度快（Cloudflare 在国内有节点）

搭建历程#

第一阶段：尝试 Halo 博客系统#

安装 Docker Desktop#

首先需要安装 Docker，因为 Halo 博客需要 Docker 运行。我下载并安装了 Docker Desktop，遇到了一些网络问题，但最终成功安装。

创建配置文件#

Claude Code 帮我创建了 docker-compose.yml 配置文件：

1
services:
2
  halo:
3
    image: halohub/halo:2.20
4
    container_name: halo-blog
5
    volumes:
6
      - ./halo-workspace:/root/.halo2
7
    ports:
8
      - "8090:8090"

遇到问题#

启动后遇到了端口配置问题，Halo 博客无法访问。经过排查，是因为 Windows 不支持 network_mode: "host" 配置。

放弃 Halo 的原因#

虽然问题可以解决，但我意识到：

Docker 运行占用资源较多
Halo 功能对我来说过于复杂
静态博客更适合我的需求

第二阶段：转向 Astro 静态博客#

Claude Code 帮我创建了一个简单的 Astro 博客：

1
项目位置：blog-astro/
2
核心文件：
3
- src/config.mjs - Astro 配置
4
- src/content.config.ts - 内容模式定义
5
- src/pages/ - 页面文件
6
- src/layouts/ - 布局文件

编写第一篇文章#

创建了三篇文章：

从零搭建个人博客 - 完整记录
如何在博客中使用图片
使用本地图片示例

本地预览#

运行 npm run dev，成功在 http://localhost:4321/ 看到了博客！

第三阶段：尝试 Mizuki 主题#

虽然简单的博客已经可以工作，但我想要更漂亮的主题。Claude Code 帮我找到了 Mizuki 主题（https://github.com/matsuzaka-yuki/Mizuki）。

下载主题#

由于网络问题，多次尝试下载失败。最终手动下载了 ZIP 文件并解压。

安装依赖#

Mizuki 使用 pnpm 包管理器（这是我第一次接触 pnpm）：

1
# 安装 pnpm
2
npm install -g pnpm
3

4
# 安装主题依赖
5
cd Mizuki
6
pnpm install

依赖安装成功！但由于网络原因，最终没有继续使用 Mizuki。

第四阶段：切换到 Fuwari 主题#

在 Claude Code 的推荐下，我发现了 Fuwari 主题（https://github.com/saicaca/fuwari）。

Fuwari 的优势#

设计简洁优雅
卡片式布局
响应式设计
性能优秀

下载和安装#

1
# 克隆主题
2
git clone https://github.com/saicaca/fuwari.git
3

4
# 安装依赖
5
cd fuwari
6
pnpm install

迁移文章#

将之前的文章从简单博客迁移到 Fuwari：

主要变化：

文件位置：从 src/content/blog/ 改为 src/content/posts/
Frontmatter：从 pubDate 改为 published
新增字段：draft、pinned、category

示例：

旧格式（简单博客）：

1
---
2
title: '文章标题'
3
description: '文章描述'
4
pubDate: 2026-02-08
5
heroImage: '/images/photo.jpg'
6
---

新格式：

1
---
2
title: '文章标题'
3
published: 2026-02-08
4
description: '文章描述'
5
tags: [标签1, 标签2]
6
category: 分类
7
draft: false
8
pinned: false
9
image: '/images/photo.jpg'
10
---

配置主题#

Claude Code 帮我修改了 src/config.ts：

1
export const siteConfig: SiteConfig = {
2
  title: "我的个人博客",
3
  subtitle: "记录学习、生活与思考",
4
  lang: "zh_CN",
5
  themeColor: {
6
    hue: 210,  // 主题色
7
    fixed: false,
8
  },
9
  banner: {
10
    enable: true,
11
    src: "assets/images/bannner.jpg",  // 横幅图片
12
    position: "center",
13
  },
14
  // ...
15
}

启动本地博客#

1
cd "F:\OneDrive - stu.hqu.edu.cn\文件树\100-Personal\130-个人项目\05-Blog construct\fuwari"
2
pnpm dev

成功在 http://localhost:4322/ 看到了漂亮的 Fuwari 博客！

第五阶段：部署到 Cloudflare Pages#

创建 GitHub 仓库#

在 GitHub 创建新仓库：Croco-blog
重新初始化 Git 历史（为了避免冲突）
推送代码到 GitHub

1
git init
2
git add .
3
git commit -m "初始化个人博客"
4
git remote add origin https://github.com/Crocodile223/Croco-blog.git
5
git push -u origin main

授权 Cloudflare Pages#

访问 https://dash.cloudflare.com
使用 GitHub 账号登录
授权 Cloudflare 访问 GitHub

部署过程#

经历了界面导航的困难（在 Workers vs Pages 之间迷失），最终找到了正确的位置：

点击 “Workers & Pages”
选择 “Connect to Git”
选择 “Croco-blog” 仓库
配置构建设置：
- Build command: pnpm build
- Output directory: dist
点击 “Deploy”

部署成功！🎉#

几分钟后，博客成功部署到：

1
https://croco-blog.pages.dev

技术栈总结#

核心技术#

静态站点生成器：Astro 5.13.10
UI 框架：Svelte 5.39.8
样式：Tailwind CSS 3.4.19
包管理器：pnpm 10.29.1
内容管理：Astro Content Collections + Markdown
部署平台：Cloudflare Pages

项目结构#

1
fuwari/
2
├── src/
3
│   ├── content/
4
│   │   ├── posts/          # 博客文章（Markdown）
5
│   │   └── config.ts       # 内容模式定义
6
│   ├── config.ts           # 主配置文件
7
│   ├── components/         # 组件
8
│   ├── layouts/            # 布局
9
│   ├── pages/              # 页面
10
│   └── styles/             # 样式
11
├── public/
12
│   ├── favicon/           # 网站图标
13
│   └── images/            # 静态图片
14
└── package.json

已发布文章#

从零搭建个人博客 - 完整记录（置顶）
如何在博客中使用图片
使用本地图片示例

遇到的问题和解决方案#

问题 1：Docker 网络连接失败#

现象：无法从 Docker Hub 下载镜像

解决：手动下载了 ZIP 文件并解压

问题 2：Halo 博客端口配置问题#

现象：localhost 拒绝连接

原因：Windows 不支持 network_mode: "host"

解决：移除该配置，使用端口映射

问题 3：Git 历史冲突#

现象：推送到 GitHub 失败

原因：Fuwari 原有仓库的历史导致冲突

解决：删除 .git 目录，重新初始化

问题 4：Cloudflare Pages 界面找不到#

现象：在 Workers 和 Pages 之间迷失

原因：界面导航不熟悉

解决：最终找到了 “Workers & Pages” → “Connect to Git”

工作流程总结#

写作流程#

1
1. 在 src/content/posts/ 创建 .md 文件
2
2. 添加 Frontmatter
3
3. 编写 Markdown 内容
4
4. 本地预览：pnpm dev
5
5. 发布：git add . → git commit → git push

部署流程#

1
1. 本地写文章
2
2. 推送到 GitHub
3
3. Cloudflare Pages 自动检测
4
4. 自动构建部署
5
5. 几分钟后在线可见

成果展示#

博客地址#

在线访问：https://croco-blog.pages.dev
GitHub 仓库：https://github.com/Crocodile223/Croco-blog

功能特性#

✅ 清爽的卡片式设计
✅ 响应式布局
✅ 亮/暗主题切换
✅ 搜索功能（Pagefind）
✅ 文章分类和标签
✅ 自动目录生成
✅ 代码高亮
✅ 数学公式支持
✅ 图片画廊

性能优势#

⚡ 静态文件加载速度极快
🔒 没有数据库，更安全
💰 完全免费托管
🌐 Cloudflare CDN 全球加速
🇨🇳 国内访问速度快

心得体会#

AI 辅助开发的优势#

作为编程新手，能在一天内完成博客搭建，主要归功于 Claude Code：

降低门槛：不需要学习复杂的技术栈
自动决策：帮我选择了最合适的方案
快速解决问题：遇到错误立即定位和修复
减少试错：避免了常见的配置错误
学习机会：在操作中也能学到知识

静态博客的好处#

对比之前的尝试，我深刻体会到静态博客的优势：

开发体验好：本地用熟悉的编辑器写文章
完全自动化：Git 推送即部署，不需要手动操作
版本控制：每次修改都有记录，可以随时回滚
成本低：Cloudflare Pages 完全免费
性能好：静态文件加载速度快
安全：没有数据库，不会被黑客攻击

克服困难的过程#

整个过程中遇到了很多困难：

网络问题：Docker 镜像下载失败、GitHub 克隆慢
配置问题：端口冲突、Git 历史冲突
界面不熟悉：Cloudflare Pages 界面导航困难

但在 Claude Code 的帮助下，所有问题都一一解决。

后续计划#

短期目标#

定期更新博客文章
优化博客样式
添加评论系统
配置自定义域名

长期目标#

添加更多技术文章
学习更多 Astro 高级功能
建立个人知识库
与其他博主交流

致谢#

搭建团队#

技术实现：Claude Code (AI 编程助手)
需求提出：我（Crocodile，编程新手）
完成时间：2026年2月8日

参考资源#

技术文档#

AI 工具#

Claude Code - 本次搭建使用的 AI 编程助手
Claude - Anthropic 出品的 AI 助手

总结#

在 Claude Code AI 助手的帮助下，我只用一天时间就成功搭建并部署了个人博客！

整个过程让我深刻体会到：

新手也能快速搭建专业级系统
AI 辅助开发极大地降低了技术门槛
静态博客 + 自动部署是完美的组合

如果你也想搭建博客但担心技术难度，不妨试试 Astro + Cloudflare Pages + AI 助手！

搭建日期：2026年2月8日 博客系统：Astro + Fuwari 部署平台：Cloudflare Pages 博客地址：https://croco-blog.pages.dev