GitHub + EdgeOne 搭建个人博客的过程

想要一个属于自己的博客，但不知道从哪里开始？本文详细记录了从零开始搭建个人博客的全过程，包括踩过的各种坑和解决方案。

为什么选择 Fuwari 主题？#

在决定搭建博客之前，我对比了多个静态博客生成器：

工具	优点	缺点
Hexo	插件丰富、中文文档多	生成速度慢、配置复杂
Hugo	构建极快	学习曲线陡峭
VuePress	Vue 生态友好	主要用于文档
Astro	性能卓越、配置简单	相对较新

最终选择了基于 Astro 5.7+ 的 Fuwari 主题，原因很简单：

零配置即可使用
完美适配移动端
内置深色模式
性能评分接近满分

一、前期准备#

1.1 所需账号#

在开始之前，你需要准备：

服务	用途	是否必需
GitHub 账号	代码托管	必需
EdgeOne 账号	静态网站部署	必需
Gitee 账号	图床（可选）	可选

1.2 环境要求#

1
# 检查 Node.js 版本（需要 18.0+）
2
node -v
3

4
# 推荐：使用 pnpm 作为包管理器
5
npm install -g pnpm

二、克隆与配置#

2.1 克隆项目#

1
# 克隆 Fuwari 项目
2
git clone https://github.com/saicaca/fuwari.git my-blog
3
cd my-blog
4

5
# 安装依赖
6
pnpm install

2.2 启动开发服务器#

1
pnpm dev

访问 http://localhost:4321/ 即可看到效果。

2.3 基本配置#

编辑 src/config.ts 文件：

1
// 站点基本信息
2
export const siteConfig: SiteConfig = {
3
  title: "你的博客标题",
4
  subtitle: "副标题描述",
5
  lang: "zh_CN",
6
  url: "https://your-domain.com",
7
  author: "你的名字",
8
};
9

10
// 个人信息卡片
11
export const profileConfig: ProfileConfig = {
12
  name: "你的名字",
13
  bio: "个性签名",
14
  avatar: "/avatar.jpg",  // 头像放在 public/ 目录
15
  email: "your-email@example.com",
16
  socialLinks: {
17
    github: "https://github.com/your-username",
18
    // 添加更多社交链接...
19
  },
20
};

三、部署到 EdgeOne#

3.1 为什么选择 EdgeOne？#

对比了多个部署平台：

平台	优点	缺点	选择
Vercel	体验好、速度快	国内访问慢	❌
Netlify	功能强大	国内访问慢	❌
EdgeOne	国内访问快、免费额度充足	需要备案域名	✅

3.2 部署步骤#

步骤 1：创建 GitHub 仓库#

1
# 初始化 git 仓库
2
git init
3
git add .
4
git commit -m "Initial commit"
5

6
# 推送到 GitHub
7
git remote add origin https://github.com/your-username/your-repo.git
8
git branch -M main
9
git push -u origin main

步骤 2：EdgeOne 配置#

登录 EdgeOne 控制台
选择「静态网站」→「新建站点」
连接 GitHub 仓库，选择分支：main

步骤 3：构建设置#

1
框架预设: Astro
2
根目录: ./
3
输出目录: dist
4
编译命令: pnpm run build
5
安装命令: pnpm install

步骤 4：开始部署#

点击「开始部署」，等待 1-2 分钟即可完成。

四、踩过的坑（重点！）#

坑 1：YAML Frontmatter 格式错误#

现象：文章发布后只显示标题，没有封面、摘要、正文。

原因：YAML 格式极其严格，任何一个空格错误都会导致解析失败。

❌ 错误写法#

1
---
2
title:文章标题
3
published:2026/02/04
4
category:软件安利
5
tags: 标签1, 标签2
6
draft: True
7
---

✅ 正确写法#

1
---
2
title: 文章标题           # 冒号后必须有空格
3
published: 2026-02-04     # 日期必须用连字符
4
category: 技术教程         # 冒号后必须有空格
5
tags: [标签1, 标签2]      # 必须用数组格式
6
draft: true               # 布尔值必须小写
7
---

YAML 四大黄金规则：

冒号后必须有空格

1
title: 文章标题  # ✅ 正确
2
title:文章标题   # ❌ 错误

日期必须用连字符

1
published: 2026-02-04  # ✅ 正确
2
published: 2026/02/04  # ❌ 错误

标签必须用数组格式

1
tags: [Astro, 教程, 前端]  # ✅ 正确
2
tags: Astro, 教程, 前端     # ❌ 错误

布尔值必须小写

1
draft: true   # ✅ 正确
2
draft: True   # ❌ 错误
3
draft: TRUE   # ❌ 错误

坑 2：导航栏抖动问题#

现象：点击「归档」「友链」等页面时，顶部导航栏会抖动一下。

原因：页面切换时 page-height-extend 元素的显示/隐藏导致高度变化。

解决方案：

移除 top-row 的 transition-all 过渡动画
在 Swup 钩子中禁用 onload-animation
完全移除 page-height-extend 逻辑

修改 src/layouts/Layout.astro：

1
window.swup.hooks.on('visit:start', (visit) => {
2
  // 禁用导航时的动画，防止抖动
3
  const animatedElements = document.querySelectorAll('.onload-animation');
4
  animatedElements.forEach(el => {
5
    el.style.opacity = '1';
6
    el.style.animation = 'none';
7
  });
8
});

坑 3：页面加载时颜色闪烁#

现象：刷新网页时会闪一下另一种配色，然后才变成正确的颜色。

原因：CSS 样式加载有延迟，导致使用了默认样式。

解决方案：在 <head> 中添加内联样式

修改 src/layouts/Layout.astro：

1
<head>
2
  <!-- 其他 head 内容 -->
3

4
  <!-- 内联渐变样式，防止闪烁 -->
5
  <style is:inline>
6
    .navbar-title-gradient,
7
    .navbar-title-gradient-icon,
8
    .gradient-text,
9
    .hacker-icon,
10
    .category-title,
11
    .decoration-title {
12
        background: linear-gradient(135deg, #0ea5e9, #8b5cf6) !important;
13
        -webkit-background-clip: text !important;
14
        -webkit-text-fill-color: transparent !important;
15
        background-clip: text !important;
16
    }
17
  </style>
18
</head>

坑 4：深色模式颜色不和谐#

现象：深色模式下，某些元素的颜色显得突兀。

原因：使用了固定的颜色值（如 #A8C398），没有跟随主题色。

解决方案：将所有固定颜色改为使用 CSS 变量 var(--primary)

1
/* ❌ 错误：固定颜色 */
2
color: #A8C398;
3

4
/* ✅ 正确：主题色变量 */
5
color: var(--primary);

深色模式下使用 oklch 色空间的半透明颜色：

1
.dark .decoration-line {
2
  border-color: oklch(0.35 0.02 var(--hue));
3
}

坑 5：Svelte 组件编译错误#

现象：搜索组件在开发服务器中无法正常显示。

原因：<style> 标签缺少 lang 属性，导致 Svelte 编译器无法正确解析。

解决方案：为 <style> 标签添加 lang="css" 属性

1
<!-- ❌ 错误：缺少 lang 属性 -->
2
<style>
3
  .search-panel {
4
    background-color: var(--float-panel-bg-opaque);
5
  }
6
</style>
7

8
<!-- ✅ 正确：添加 lang 属性 -->
9
<style lang="css">
10
  .search-panel {
11
    background-color: var(--float-panel-bg-opaque);
12
  }
13
</style>

坑 6：图片加载延迟#

现象：打开网站时，左侧二维码和封面图片有明显延迟。

原因：默认使用了 loading="lazy" 延迟加载。

解决方案：

关键图片移除 loading="lazy"
添加 loading="eager" 和 fetchpriority="high"
外部图片下载到本地托管

修改 src/components/misc/ImageWrapper.astro：

1
<img
2
  src={src}
3
  alt={alt}
4
  loading="eager"
5
  fetchpriority="high"
6
/>

坑 7：分类对齐问题#

现象：文章分类的名称和数字对齐不统一。

尝试的方案：

使用固定宽度 width: 80px → 数字多的时候溢出
使用 text-align: left → 不美观
使用 justify-content: center → 数字没有靠右

最终方案：

1
.category-name {
2
  flex: 1;           /* 占据剩余空间 */
3
  text-align: center; /* 名称居中 */
4
}
5

6
.category-count {
7
  /* 数字自然靠右 */
8
}

使用 flex: 1 让名称占据剩余空间并居中，数字徽章自然靠右。

坑 8：文章导入时图片 URL 错误#

现象：批量导入文章后，有些封面图显示无效。

原因：正则表达式匹配到了错误的图片 URL，例如：

1
image: generate:  # ❌ 这不是有效 URL

实际内容是 ![image: generate:](https://...)

解决方案：添加 URL 验证

1
// 只接受有效的 URL 格式
2
if (url.match(/^https?:\/\//) || url.match(/^\//)) {
3
  coverImage = url;
4
}

坑 9：EdgeOne 构建时 import.meta.glob 不工作#

现象：本地开发正常，但 EdgeOne 构建后数据不显示。

原因：import.meta.glob 在 EdgeOne 构建环境下无法正确加载 JSON 文件。

错误代码：

1
---
2
// ❌ 在 EdgeOne 构建时不工作
3
const sponsorFiles = import.meta.glob('../../data/sponsors/*.json', { eager: true });
4
const sponsors = Object.values(sponsorFiles).map(m => m.default);
5
---

解决方案：将数据直接内联到文件中

1
---
2
// ✅ 直接内联数据
3
const sponsors = [
4
  { "name": "赞助者1", "avatar": "https://...", "date": "2026-01-01" },
5
  { "name": "赞助者2", "avatar": "https://...", "date": "2026-01-02" },
6
  // ...更多数据
7
];
8
---

经验教训：在 EdgeOne 等云端构建环境中，尽量避免使用动态导入，对于静态数据直接内联更可靠。

坑 10：浮动按钮挡住大纲#

现象：文章页面的评论/回到顶部按钮挡住了右侧大纲的部分区域。

原因：按钮位置设置过高。

解决方案：调整浮动按钮的 bottom 值

修改 src/components/control/BackToTop.astro：

1
.back-to-top-btn
2
  // 从 bottom: 10rem 改为 bottom: 6rem（向下移动 4rem）
3

4
#go-to-comments-btn
5
  // 从 bottom: 14.5rem 改为 bottom: 10.5rem（向下移动 4rem）

五、配色系统设计#

设计理念#

博客采用冷紫蓝系作为唯一签名色，打造冷静编辑部的视觉氛围。

设计原则：

背景作为舞台 - 更深的背景，更浅的卡片
标题作为判断 - 更强的视觉层次
极端色彩克制 - 最少的颜色，创造可记忆的身份

配色方案#

主题配置（src/config.ts）：

1
themeColor: {
2
  hue: 268,        // 冷紫蓝系
3
  fixed: true,
4
}

颜色应用：

元素	颜色	说明
背景色	`oklch(0.12 0.01 268)`	深色纯色背景
主题渐变	`#0ea5e9 → #8b5cf6`	蓝紫渐变，用于标题和图标
分类悬停	`#b7f605` + 黑字	亮绿色点缀，唯一暖色

渐变元素#

使用蓝紫渐变的元素：

导航栏网站名称和图标
分类标题（“文章分类”）
公众号标题
Hacker 风格装饰图标

内联样式（防止 FOUC 闪烁）：

1
<style is:inline>
2
.navbar-title-gradient,
3
.navbar-title-gradient-icon,
4
.gradient-text,
5
.hacker-icon,
6
.category-title,
7
.decoration-title {
8
    background: linear-gradient(135deg, #0ea5e9, #8b5cf6) !important;
9
    -webkit-background-clip: text !important;
10
    -webkit-text-fill-color: transparent !important;
11
    background-clip: text !important;
12
}
13
</style>

六、特色功能实现#

6.1 评论/回到顶部浮动按钮#

右下角浮动按钮，提供快捷导航：

功能特性：

默认显示”评论”按钮，点击跳转到评论区
点击后切换为”回到顶部”按钮
位置下移避免挡住大纲

修改文件：src/components/control/BackToTop.astro

6.2 表格样式优化#

表格采用表头浅色、数据行深色的配色方案：

样式配置（src/styles/markdown-extend.styl）：

1
thead th
2
  background: var(--btn-plain-bg-hover)  // 表头：浅色
3

4
tbody tr
5
  background: var(--btn-regular-bg)      // 数据行：深色

6.3 自动提取封面和摘要#

无需手动填写，系统自动处理：

1
---
2
title: 文章标题
3
published: 2026-02-06
4
tags: [标签]
5
category: Technical
6
# 无需填写 image 和 description
7
---
8

9
第一段文字会自动成为摘要...
10

11
文章正文...

封面：自动提取第一张图片
摘要：自动提取第一段文字（文章页隐藏，避免重复）

6.4 微信二维码弹窗#

点击微信图标弹出霓虹灯风格弹窗，支持一键复制微信号。

修改 src/layouts/MainGridLayout.astro 添加弹窗 HTML 和 JavaScript。

6.5 Giscus 评论区#

基于 GitHub Discussions 的评论系统，无需数据库。

配置步骤：

在 GitHub 仓库启用 Discussions
访问 https://giscus.app 获取配置
更新 src/pages/posts/[...slug].astro

1
<div id="giscus-container"
2
    data-repo="你的用户名/仓库名"
3
    data-repo-id="R_kgDOxxxxxxxxx"
4
    data-category="Announcements"
5
    data-category-id="DIC_kwDOxxxxxxxxx"
6
    data-mapping="pathname"
7
    data-theme="preferred_color_scheme"
8
    data-lang="zh-CN"
9
></div>

6.6 文章分类功能#

自动统计每个分类的文章数量，点击查看分类文章。

分类规则：

分类	关键词
Software	Typora, PicList, 快捷键, 图床, 工具
Technical	教程, 部署, 搭建, 安装, 完整指南
AIHacks	Claude, ChatGPT, GPT, 提示词, LLM

七、常用命令#

1
# 创建新文章
2
npm run new-post "文章标题"
3

4
# 启动开发服务器
5
npm run dev
6

7
# 构建生产版本
8
npm run build
9

10
# 预览构建结果
11
npm run preview
12

13
# 批量导入文章
14
node scripts/import-posts.cjs
15

16
# 更新文章分类
17
node scripts/update-categories.cjs

八、性能优化建议#

7.1 图片优化#

使用 WebP 格式（体积更小）
关键图片添加 fetchpriority="high"
非关键图片使用 loading="lazy"

7.2 字体优化#

使用 CDN 加载霞鹜文楷字体：

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/lxgw-wenkai-webfont@1.7.0/style.css" />

7.3 构建优化#

Astro 默认进行代码分割和 tree-shaking，无需额外配置。

九、总结#

时间分配#

任务	耗时
项目配置	1 小时
部署上线	30 分钟
修复 YAML 问题	2 小时
解决导航栏抖动	1 小时
性能优化	1 小时
修复构建问题	1 小时
其他调整	2 小时
总计	约 9 小时

经验总结#

YAML 格式极其严格：一个空格错误就会导致整篇文章无法显示
使用 CSS 变量：避免固定颜色值，让主题自动适配
关键资源优先加载：首屏图片不要使用 loading="lazy"
测试深色模式：确保在深色模式下也能正常显示
善用 Astro 的自动提取：减少手动填写的工作量
注意云端构建差异：import.meta.glob 在云端可能不工作，静态数据直接内联更可靠

下一步#

博客已经上线，接下来可以：

完善个人信息和社交链接
配置自定义域名（需要备案）
添加更多文章
优化 SEO（搜索引擎优化）
集成统计工具（如 Umami）

祝你搭建顺利！有任何问题欢迎在评论区留言。

发现新文章