2024-2026年个人博客搭建完整指南#

1.1 技术背景与趋势#

2024至2026年，个人博客技术方案经历了重大变革。传统的静态站点生成器（SSG）依然是主流选择，但新兴的”孤岛架构”和”无头CMS”方案正在快速崛起。对于曾经使用Hexo的用户而言，现代方案在构建速度、内容管理便捷性以及性能优化方面有了显著提升 [1]。

Astro凭借其革命性的”孤岛架构”成为2025年最受关注的框架，它允许在静态页面中按需注入交互组件，极大减少了客户端JavaScript负载 [6]。Hugo则以毫秒级的构建速度稳居高位，适合文章量大的技术博客 [2]。NotionNext作为”零代码”方案，让创作者可以直接在Notion中写作并自动发布，彻底摆脱了Git命令的束缚 [10]。

1.2 三大推荐方案对比#

1.3 如何选择适合你的方案#

根据你的具体需求，建议按以下原则选择：

• 选择方案A（Astro）：如果你希望博客具有现代感的设计、优秀的性能评分，并且不介意学习一点新技术。这是原Hexo用户的最佳升级路径。
• 选择方案B（NotionNext）：如果你讨厌折腾代码，希望随时随地用手机或电脑在Notion中写完即发布。写作体验是三个方案中最好的 [15]。
• 选择方案C（Hugo）：如果你追求极致的构建速度和稳定性，或者已有大量Markdown格式的文章需要迁移。万级文章的博客，Hugo构建仅需数秒 [2]。

2.1 环境准备#

在开始之前，需要安装以下开发环境：

第一步：安装Node.js（18.x或20.x LTS版本）

访问 https://nodejs.org 下载并安装LTS版本。安装完成后验证：

1
node -v    # 应显示 v18.x.x 或 v20.x.x
2
npm -v     # 应显示 9.x.x 或更高

第二步：安装Git

访问 https://git-scm.com 下载并安装。安装完成后配置用户信息：

1
git config --global user.name "你的GitHub用户名"
2
git config --global user.email "你的邮箱地址"

第三步：安装VS Code（推荐）

访问 https://code.visualstudio.com 下载安装，并安装以下扩展：

• Astro（官方扩展，语法高亮和智能提示）
• Tailwind CSS IntelliSense（样式提示）

2.2 创建Astro项目#

打开终端，执行以下命令创建新项目：

1
# 创建Astro项目（推荐使用blog模板）
2
npm create astro@latest my-blog
3

4
# 交互式配置选项建议：
5
# - How would you like to start? → Use blog template
6
# - Do you plan to write TypeScript? → Yes (推荐)
7
# - Install dependencies? → Yes
8
# - Initialize a git repository? → Yes

创建完成后进入项目目录：

1
cd my-blog
2
npm run dev

此时访问 http://localhost:4321 即可看到博客预览。

2.3 安装推荐主题（Fuwari主题）#

Fuwari是2025年最受欢迎的Astro博客主题，设计现代、动效精美。如果你更喜欢直接使用主题而非默认模板，可以按以下方式操作：

1
# 方式一：直接克隆Fuwari主题（推荐新手）https://github.com/saicaca/fuwari
2
# git clone https://github.com/saicaca/fuwari.git my-blog
3

4
npm create fuwari@latest
5
cd my-blog
6
npm install
7
npm run dev

1
# 方式二：使用AstroPaper主题（更简洁）
2
git clone https://github.com/satnaing/astro-paper.git my-blog
3
cd my-blog
4
npm install
5
npm run dev

主题配置文件修改（以Fuwari为例）：

编辑 src/config.ts 文件，修改以下关键配置：

1
export const siteConfig = {
2
  title: '你的博客名称',
3
  subtitle: '你的博客副标题',
4
  lang: 'zh_CN',
5
  profile: {
6
    author: '你的名字',
7
    description: '一句话介绍自己',
8
    avatar: '/avatar.png'  // 将头像放到public目录
9
  }
10
}

2.4 本地开发与文章编写#

Astro使用Markdown/MDX格式编写文章。文章存放在 src/content/posts/ 目录下。

创建新文章：

在 src/content/posts/ 目录下创建新的 .md 文件，例如 my-first-post.md：

1
---
2
title: 我的第一篇博客
3
published: 2026-03-02
4
description: '这是文章描述'
5
tags: ['博客', '教程']
6
category: '技术'
7
draft: false
8
---
9

10
## 正文内容
11

12
这里写你的文章正文，支持标准Markdown语法。
13

14
### 代码高亮示例
15

16
\`\`\`javascript
17
console.log('Hello Astro!');
18
\`\`\`
19

20
### 图片引用
21

22
![图片描述](/images/example.png)

本地预览命令：

1
npm run dev      # 开发模式，支持热更新
2
npm run build    # 构建生产版本
3
npm run preview  # 预览构建结果

2.5 GitHub仓库创建与推送#

第一步：在GitHub创建新仓库

1. 登录 https://github.com
2. 点击右上角 ”+” → “New repository”
3. 仓库名建议：my-blog 或 你的用户名.github.io
4. 选择 Public，不要勾选初始化README
5. 点击 “Create repository”

第二步：配置SSH密钥（如果尚未配置）

1
# 生成SSH密钥
2
ssh-keygen -t ed25519 -C "你的邮箱地址"
3

4
# 查看公钥
5
cat ~/.ssh/id_ed25519.pub

将显示的公钥内容复制，然后：

1. 打开 GitHub → Settings → SSH and GPG keys
2. 点击 “New SSH key”
3. 粘贴公钥并保存

第三步：推送代码到GitHub

1
# 在项目目录下执行
2
git add .
3
git commit -m "Initial commit"
4
git branch -M main
5
git remote add origin git@github.com:你的用户名/my-blog.git
6
git push -u origin main

2.6 Cloudflare Pages部署#

Cloudflare Pages提供无限免费带宽和自动SSL证书，是2025年最推荐的静态站点部署平台 [4][9]。

第一步：注册Cloudflare账号

访问 https://dash.cloudflare.com/sign-up 注册账号（免费）。

第二步：创建Pages项目

1. 登录Cloudflare Dashboard
2. 左侧菜单选择 “Workers & Pages”
3. 点击 “Create application” → “Pages” → “Connect to Git”
4. 授权并选择你的GitHub仓库
5. 配置构建设置：

6. 点击 “Save and Deploy”

等待2-3分钟，部署完成后会获得一个 xxx.pages.dev 的域名，即可访问你的博客。

第三步：配置环境变量（如需要）

在 Settings → Environment variables 中添加：

• NODE_VERSION：18（确保构建环境Node版本）

2.7 腾讯云域名绑定#

如果你在腾讯云已有域名，按以下步骤绑定到Cloudflare Pages：

第一步：在Cloudflare添加自定义域名

1. 进入你的Pages项目 → Custom domains
2. 点击 “Set up a custom domain”
3. 输入你的域名（如 blog.yourdomain.com）
4. Cloudflare会显示需要配置的CNAME记录

第二步：在腾讯云配置DNS解析

1. 登录腾讯云控制台 → 云解析DNS
2. 选择你的域名 → 添加记录
3. 配置如下：

4. 等待DNS生效（通常5-10分钟）

第三步：验证域名

回到Cloudflare Pages的Custom domains页面，点击 “Activate domain”。Cloudflare会自动为你配置SSL证书。

2.8 常见问题与解决方案#

3.1 Notion账号准备与数据库模板复制#

第一步：注册Notion账号

访问 https://www.notion.so 注册账号（免费版即可）。

第二步：复制博客数据库模板

1. 访问NotionNext官方模板：https://tanghh.notion.site/02ab3b8678004aa69e9e415905ef32a5
2. 点击右上角 “Duplicate”（复制）将模板复制到你的Notion空间
3. 复制后你会得到一个包含示例文章的数据库

第三步：获取Notion页面ID

1. 在浏览器中打开你复制的数据库页面
2. 复制URL中的页面ID，格式如下：

1
https://www.notion.so/你的空间/02ab3b8678004aa69e9e415905ef32a5
2
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3
                              这部分就是PAGE_ID

第四步：创建Notion Integration

1. 访问 https://www.notion.so/my-integrations
2. 点击 “New integration”
3. 命名为 “NotionNext”，选择关联的空间
4. 创建后复制 “Internal Integration Token”（以secret_开头）

第五步：授权Integration访问数据库

1. 回到你的博客数据库页面
2. 点击右上角 ”…” → “Add connections”
3. 选择刚创建的 “NotionNext” Integration

3.2 Fork NotionNext项目到GitHub#

1. 访问 https://github.com/tangly1024/NotionNext
2. 点击右上角 “Fork” 按钮
3. Fork到你自己的GitHub账号下

3.3 配置环境变量#

在部署前，你需要准备以下环境变量：

3.4 Vercel一键部署#

第一步：注册Vercel账号

访问 https://vercel.com 使用GitHub账号登录（推荐）。

第二步：导入项目

1. 点击 “Add New…” → “Project”
2. 选择 “Import Git Repository”
3. 找到你Fork的NotionNext仓库，点击 “Import”

第三步：配置环境变量

在部署配置页面的 “Environment Variables” 部分添加：

• NOTION_PAGE_ID：你的页面ID
• NOTION_ACCESS_TOKEN：你的Integration Token

第四步：部署

点击 “Deploy”，等待2-3分钟即可完成部署。部署成功后会获得一个 xxx.vercel.app 域名。

3.5 腾讯云域名绑定到Vercel#

第一步：在Vercel添加域名

1. 进入项目 → Settings → Domains
2. 输入你的域名（如 blog.yourdomain.com）
3. 点击 “Add”

第二步：在腾讯云配置DNS

Vercel会提供需要配置的记录，通常为：

在腾讯云云解析中添加此记录即可。

3.6 日常写作流程#

NotionNext的日常写作流程极其简单：

1. 打开Notion（手机/电脑/网页均可）
2. 在数据库中新建页面
3. 填写文章属性：
   • title：文章标题
   • status：设为 “Published” 发布
   • type：设为 “Post”
   • date：发布日期
   • tags：文章标签
4. 编写正文内容
5. 保存即发布（Vercel会自动重新构建，通常1-2分钟生效）

提示：如果更新不及时，可在Vercel项目中手动点击 “Redeploy” 触发更新。

4.1 Hugo安装#

Windows安装：

1
# 方式一：使用winget（推荐）
2
winget install Hugo.Hugo.Extended
3

4
# 方式二：使用Scoop
5
scoop install hugo-extended
6

7
# 方式三：手动下载
8
# 访问 https://github.com/gohugoio/hugo/releases
9
# 下载 hugo_extended_xxx_windows-amd64.zip
10
# 解压后将hugo.exe所在目录添加到系统PATH

macOS安装：

1
brew install hugo

Linux安装：

1
# Debian/Ubuntu
2
sudo apt install hugo
3

4
# 或使用Snap
5
sudo snap install hugo --channel=extended

验证安装：

1
hugo version
2
# 应显示 hugo v0.xxx.x+extended ...

4.2 创建站点与主题安装#

第一步：创建Hugo站点

1
hugo new site my-blog
2
cd my-blog
3
git init

第二步：安装PaperMod主题（推荐）

1
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

第三步：配置站点

编辑项目根目录的 hugo.toml（或 config.toml）：

1
baseURL = 'https://你的用户名.github.io/'
2
languageCode = 'zh-cn'
3
title = '你的博客名称'
4
theme = 'PaperMod'
5

6
[params]
7
  author = '你的名字'
8
  description = '博客描述'
9
  defaultTheme = 'auto'
10
  ShowReadingTime = true
11
  ShowShareButtons = true
12
  ShowPostNavLinks = true
13
  ShowBreadCrumbs = true
14
  ShowCodeCopyButtons = true
15

16
[params.homeInfoParams]
17
  Title = '欢迎来到我的博客'
18
  Content = '一句话介绍'
19

20
[[params.socialIcons]]
21
  name = 'github'
22
  url = 'https://github.com/你的用户名'
23

24
[menu]
25
[[menu.main]]
26
  identifier = 'archives'
27
  name = '归档'
28
  url = '/archives/'
29
  weight = 10
30

31
[[menu.main]]
32
  identifier = 'tags'
33
  name = '标签'
34
  url = '/tags/'
35
  weight = 20

4.3 本地预览与文章编写#

创建新文章：

1
hugo new posts/my-first-post.md

编辑 content/posts/my-first-post.md：

1
---
2
title: "我的第一篇博客"
3
date: 2026-03-02
4
draft: false
5
tags: ["博客", "Hugo"]
6
categories: ["技术"]
7
---
8

9
## 正文内容
10

11
这里写你的文章正文...

本地预览：

1
hugo server -D
2
# 访问 http://localhost:1313

4.4 GitHub Actions自动部署配置#

第一步：创建GitHub仓库

创建名为 你的用户名.github.io 的仓库（必须是这个格式）。

第二步：创建GitHub Actions配置

在项目中创建 .github/workflows/deploy.yml：

1
name: Deploy Hugo site to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
permissions:
9
  contents: read
10
  pages: write
11
  id-token: write
12

13
concurrency:
14
  group: pages
15
  cancel-in-progress: false
16

17
defaults:
18
  run:
19
    shell: bash
20

21
jobs:
22
  build:
23
    runs-on: ubuntu-latest
24
    env:
25
      HUGO_VERSION: 0.124.0
26
    steps:
27
      - name: Install Hugo CLI
28
        run: |
29
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
30
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
31
      - name: Checkout
32
        uses: actions/checkout@v4
33
        with:
34
          submodules: recursive
35
      - name: Setup Pages
36
        id: pages
37
        uses: actions/configure-pages@v4
38
      - name: Build with Hugo
39
        env:
40
          HUGO_ENVIRONMENT: production
41
        run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
42
      - name: Upload artifact
43
        uses: actions/upload-pages-artifact@v3
44
        with:
45
          path: ./public
46

47
  deploy:
48
    environment:
49
      name: github-pages
50
      url: ${{ steps.deployment.outputs.page_url }}
51
    runs-on: ubuntu-latest
52
    needs: build
53
    steps:
54
      - name: Deploy to GitHub Pages
55
        id: deployment
56
        uses: actions/deploy-pages@v4

第三步：启用GitHub Pages

1. 进入仓库 Settings → Pages
2. Source选择 “GitHub Actions”

第四步：推送代码

1
git add .
2
git commit -m "Initial commit"
3
git branch -M main
4
git remote add origin git@github.com:你的用户名/你的用户名.github.io.git
5
git push -u origin main

推送后GitHub Actions会自动构建并部署，几分钟后即可通过 https://你的用户名.github.io 访问。

4.5 腾讯云域名绑定到GitHub Pages#

第一步：在腾讯云添加DNS解析

第二步：在GitHub配置自定义域名

1. 仓库 Settings → Pages → Custom domain
2. 输入你的域名，点击Save
3. 勾选 “Enforce HTTPS”

4.6 CNAME文件配置避免被覆盖#

为防止每次部署后CNAME配置丢失，需要在源码中创建CNAME文件：

1
# 在static目录下创建CNAME文件
2
echo "blog.yourdomain.com" > static/CNAME

Hugo构建时会自动将 static 目录的内容复制到 public 目录 [16]。

5.1 登录腾讯云控制台#

1. 访问 https://console.cloud.tencent.com
2. 登录你的腾讯云账号
3. 在控制台搜索”云解析 DNS”或直接访问域名管理页面

5.2 DNS解析记录添加#

CNAME记录配置方法：

1. 选择你要配置的域名
2. 点击”添加记录”
3. 填写以下信息：

各平台对应记录值：

5.3 SSL证书说明#

好消息是，以上三个部署平台都会自动处理SSL证书：

• Cloudflare Pages：自动签发并续签免费SSL证书
• Vercel：自动签发Let’s Encrypt证书
• GitHub Pages：自动签发免费证书（需勾选Enforce HTTPS）

你无需手动申请或配置SSL证书。

5.4 生效时间与验证方法#

DNS记录添加后，通常需要5-30分钟生效（取决于TTL设置和DNS缓存）。

验证方法：

1
# 方法一：使用nslookup检查解析
2
nslookup blog.yourdomain.com
3

4
# 方法二：使用dig命令（Linux/Mac）
5
dig blog.yourdomain.com CNAME
6

7
# 方法三：直接在浏览器访问域名

如果DNS已生效但仍无法访问，请检查部署平台的自定义域名配置是否完成。

6.1 原Hexo文章迁移方法#

好消息是，Hexo、Hugo、Astro都使用Markdown格式的文章，迁移成本极低。

迁移步骤：

1. 复制文章文件：将Hexo的 source/_posts/ 目录下的所有 .md 文件复制到新框架的文章目录

   • Astro：src/content/posts/
   • Hugo：content/posts/
   • NotionNext：需要手动复制到Notion

2. 调整Front Matter：不同框架的文章元数据格式略有差异

3. 检查图片路径：确保图片路径正确
   • 建议将图片统一放到 public/images/ 或 static/images/ 目录
   • 文章中使用 /images/xxx.png 格式引用

6.2 图片资源迁移建议#

推荐做法：

• 个人博客图片不多时，直接放在项目 public/images 目录
• 图片较多时，使用对象存储配合CDN

6.3 各方案优缺点总结#

6.4 推荐的写作工具#

6.5 常见问题FAQ#

Q1：部署后样式丢失怎么办？ A：检查构建输出目录配置是否正确。Astro是 dist，Hugo是 public。

Q2：自定义域名配置后显示证书错误？ A：等待10-30分钟让平台自动签发SSL证书。如果长时间未解决，检查DNS解析是否正确。

Q3：文章更新后网站没有变化？ A：

• Cloudflare/Vercel/GitHub：推送代码后会自动触发重新部署
• NotionNext：可能需要等待缓存刷新或手动Redeploy

Q4：GitHub Pages被墙无法访问怎么办？ A：建议迁移到Cloudflare Pages或Vercel，两者国内访问相对稳定。

Q5：如何提升博客SEO？ A：

• 确保每篇文章有完整的title、description
• 配置站点地图（sitemap）
• 向Google Search Console提交站点

Q6：Node.js版本错误导致构建失败？ A：在部署平台添加环境变量 NODE_VERSION=18 或 NODE_VERSION=20。