从零搭建个人技术博客

这篇是本站的第一篇文章，记录了如何从零开始搭建这个博客的完整过程。我会解释每一步涉及的概念和知识，适合完全零基础的新手阅读。

0. 前置知识：你需要知道什么？

在看这篇教程之前，你只需要知道：

概念	一句话解释
文件	你电脑上的文档、图片、代码，都是文件
文件夹/目录	用来装文件的容器
命令行/终端	一个黑窗口，通过打字来操作电脑（不用鼠标）
浏览器	Chrome、Edge 这种上网用的软件

如果上面四个概念你都没问题，就可以开始了。

1. 什么是"静态网站"？

你平时看到的网站怎么运作的？

当你打开一个网站，电脑背后发生了什么？以淘宝为例：

你打开淘宝 → 浏览器发请求 → 淘宝的服务器收到请求 
→ 查数据库，找到商品信息 → 动态拼出一个网页 → 返回给你

这是动态网站——每次访问都要"现场做"一个新页面。需要服务器一直在后台运行，需要数据库。

静态网站不同在哪？

你打开我的博客 → 浏览器发请求 → Cloudflare 直接丢一个提前做好的 HTML 文件给你

静态网站就是一摞提前做好的 HTML 页面，有人访问时直接发出去就行。好处：

不需要服务器（部署在 CDN 上）
速度快（不用现场算）
免费部署（Cloudflare Pages、GitHub Pages 等）

Vitepress 的角色

VitePress 是一个静态站点生成器。它做的事情很简单：

你写 Markdown 文件 → VitePress 把 md 变成 HTML → 生成一个完整的网站

你专注于写内容，VitePress 帮你搞定页面布局、导航、搜索、侧边栏这些技术活。

2. 什么是 Node.js 和 npm？

Node.js

通常 JavaScript 只能运行在浏览器里。Node.js 让 JavaScript 能在你的电脑上运行。

bash

node --version  # 能跑 JavaScript 程序的证据

npm（Node Package Manager）

npm 是 JavaScript 的"应用商店"。当你的项目需要用到别人写好的代码（就叫"包"或"依赖"），用 npm 下载：

bash

npm install vitepress  # 下载 VitePress 这个包

下载的东西会放到 node_modules/ 目录里。你不需要关心里面有什么，只需要知道 package.json 里记录了需要哪些包就行：

json

{
  "scripts": {
    "dev": "vitepress dev docs",   // 本地预览
    "build": "vitepress build docs", // 生成静态网站
    "preview": "vitepress preview docs" // 预览构建结果
  }
}

之后你只需要 npm run dev，npm 就自动运行对应的命令。

3. 什么是 Git 和 GitHub？

版本管理是什么？

你写论文时是不是有过这样的经历？

论文v1.docx  →  论文v2.docx  →  论文最终版.docx  →  论文绝对不会改了.docx

Git 就是解决这个问题的工具。它像一个"时光机"：

bash

git init          # 在这个文件夹开启时间旅行
git add .         # 把所有文件放进"准备区"
git commit -m "修了一个bug"  # 拍一张快照，附上备注

每次 commit 都是一张快照，任何时候都能回退到历史状态。

GitHub 是什么？

Git 管本地，GitHub 管云端。你 git push 把本地代码推到 GitHub，相当于 把"时光机"备份到了云端。

公开仓库（Public）：全世界都能看到你的代码
私有仓库（Private）：只有你能看到

我们的博客就是私有仓库——源代码你看不到，但生成的网站公开可访问。

常用 Git 命令

bash

# 查看仓库状态
git status

# 添加所有改动
git add .

# 提交（建快照）
git commit -m "描述这次改了什么"

# 推送到 GitHub
git push

# 查看提交历史
git log --oneline

4. 什么是 SSH Key？

为什么要用 SSH？

GitHub 需要确认"你是你"才能让你 push 代码。有两种方式：

方式	操作	安全度
HTTPS	每次输密码	一般
SSH	配对钥匙，以后自动识别	更安全

SSH Key 原理

你的电脑生成一对钥匙：
├── 私钥（github_blog）    ← 放在你电脑上，谁也不给
└── 公钥（github_blog.pub）← 放到 GitHub 网站上

当你 git push 时，GitHub 用公钥给你出一道题，只有持有对应私钥的人才能解出来。解对了，就放行。

bash

# 生成钥匙（只需要做一次）
ssh-keygen -t ed25519 -f ~/.ssh/github_blog

# ~/.ssh/config 告诉 Git 用哪把钥匙
Host github.com
  HostName ssh.github.com
  Port 443          # 中国用户常见：22 端口被封，用 443
  IdentityFile ~/.ssh/github_blog

为什么用端口 443？

GitHub SSH 默认走 22 端口，但这个端口在中国经常被运营商封掉。ssh.github.com 支持通过 443 端口连接（HTTPS 端口，不会被封）。

5. 什么是 VitePress？

VitePress 的词源拆解：

Vite：法语"快"的意思，底层用的构建工具叫 Vite，确实非常快
Press：出版、印刷

VitePress 是 Vue 团队 维护的文档站生成器，专门给写技术文档用。

为什么选 VitePress 而不是其他？

框架	适合场景	学习成本
VitePress	技术文档、博客	⭐ 很低
Hugo	通用博客	⭐⭐ 中等
Hexo	个人博客	⭐⭐ 中等
Next.js	复杂网站	⭐⭐⭐ 较高
Docusaurus	文档站	⭐⭐ 中等

对零基础来说，VitePress 是最简单的——它自带导航、侧边栏、搜索、代码高亮，开箱即用。

项目目录结构

text

tech-blog/
├── .vitepress/
│   └── config.mts         # 站点配置（侧边栏、导航、主题）
├── docs/                  # 所有页面放在这里
│   ├── index.md           # 首页
│   ├── about.md           # 关于页
│   └── posts/             # 文章目录
│       ├── frontend/      # 前端文章
│       ├── backend/       # 后端文章
│       ├── cs-basics/     # 计算机基础文章
│       ├── tools/         # 工具与配置文章
│       └── projects/      # 项目复盘文章
├── CLAUDE.md              # AI Agent 操作手册
├── CHANGELOG.md           # 博客变更日志
└── package.json           # npm 项目配置

VitePress 的三个常用命令

bash

npm run dev      # 启动本地预览（http://localhost:5173）
npm run build    # 生成静态网站到 docs/.vitepress/dist/
npm run preview  # 本地预览构建结果

6. 什么是 Cloudflare Pages？

Cloudflare 是什么？

Cloudflare 是一家提供 CDN（内容分发网络）和网络安全服务的公司。Pages 是它旗下专门托管静态网站的产品。

为什么选 Cloudflare Pages？

平台	私有仓库支持	免费额度	速度
Cloudflare Pages	✅	无限流量	全球 CDN
GitHub Pages	❌（免费版只能公开）	100GB/月	一般
Vercel	✅	100GB/月	极快

因为我们的仓库是私有的，GitHub Pages 免费版不支持，所以选 Cloudflare Pages。

自动部署原理

你：git push → GitHub
          ↓（GitHub 通知 Cloudflare）
Cloudflare Pages：自动拉取代码 → 执行 npm run build → 把 dist/ 发到 CDN
          ↓
用户访问 xxx.pages.dev → CDN 就近返回 HTML

整个过程你只需要 git push，其他全自动。

7. 搭建全过程回顾

准备环境

bash

# 检查 Node.js 是否安装
node --version   # v24.16.0
npm --version    # 11.13.0

创建项目

bash

# 初始化 npm 项目
npm init -y

# 安装 VitePress
npm install -D vitepress

配置网站

创建 .vitepress/config.mts，配置侧边栏和导航。

typescript

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '技术博客',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '文章', link: '/posts/' }
    ],
    sidebar: { /* 侧边栏配置 */ }
  }
})

写文章

在 docs/posts/ 下的对应目录创建 .md 文件：

markdown

---
date: 2026-07-17
category: tools
tags: [博客, VitePress]
---

# 我的文章标题

文章内容...

初始化和推送 Git

bash

git init
git add .
git commit -m "初始化博客"
git remote add origin git@github.com:frostspine/tech-blog.git
git push -u origin main

配置 SSH Key

bash

ssh-keygen -t ed25519 -f ~/.ssh/github_blog
# 把生成的 .pub 公钥添加到 GitHub Settings > SSH Keys

部署到 Cloudflare Pages

Cloudflare Dashboard → Workers & Pages → Create
连接 GitHub 仓库
Build command: npm run build
Output directory: docs/.vitepress/dist

最终效果

网站地址：tech-blog-c9x.pages.dev
源代码：github.com/frostspine/tech-blog（私有）

8. 知识地图

mermaid

graph TD
    A[你用 Markdown 写文章] --> B[VitePress 生成 HTML]
    B --> C[Git 管理所有文件版本]
    C --> D[git push 到 GitHub 私有仓库]
    D --> E[Cloudflare Pages 自动构建部署]
    E --> F[用户访问你的网站]
    
    G[Node.js/npm] -.-> B
    H[SSH Key] -.-> D
    I[Cloudflare CDN] -.-> F

9. 常用命令速查

bash

# 本地预览（边写边看效果）
npm run dev

# 构建 + 部署
git add .
git commit -m "新增文章：xxx"
git push

# 查看 Git 状态
git status

# 查看提交日志
git log --oneline

# 回退到上一个版本（如果改坏了）
git checkout HEAD -- 文件名

这是本站的第一篇文章。接下来的每一篇文章，都会像这篇一样，一步步带你理解背后的原理，而不是只给步骤。

从零搭建个人技术博客 ​

0. 前置知识：你需要知道什么？ ​

1. 什么是"静态网站"？ ​

你平时看到的网站怎么运作的？ ​

静态网站不同在哪？ ​

Vitepress 的角色 ​

2. 什么是 Node.js 和 npm？ ​

Node.js ​

npm（Node Package Manager） ​

3. 什么是 Git 和 GitHub？ ​

版本管理是什么？ ​

GitHub 是什么？ ​

常用 Git 命令 ​

4. 什么是 SSH Key？ ​

为什么要用 SSH？ ​

SSH Key 原理 ​

5. 什么是 VitePress？ ​

为什么选 VitePress 而不是其他？ ​

项目目录结构 ​

VitePress 的三个常用命令 ​

6. 什么是 Cloudflare Pages？ ​

Cloudflare 是什么？ ​

为什么选 Cloudflare Pages？ ​

自动部署原理 ​

7. 搭建全过程回顾 ​

准备环境 ​

创建项目 ​

配置网站 ​

写文章 ​

初始化和推送 Git ​

配置 SSH Key ​

部署到 Cloudflare Pages ​

最终效果 ​

8. 知识地图 ​

9. 常用命令速查 ​

从零搭建个人技术博客

0. 前置知识：你需要知道什么？

1. 什么是"静态网站"？

你平时看到的网站怎么运作的？

静态网站不同在哪？

Vitepress 的角色

2. 什么是 Node.js 和 npm？

Node.js

npm（Node Package Manager）

3. 什么是 Git 和 GitHub？

版本管理是什么？

GitHub 是什么？

常用 Git 命令

4. 什么是 SSH Key？

为什么要用 SSH？

SSH Key 原理

5. 什么是 VitePress？

为什么选 VitePress 而不是其他？

项目目录结构

VitePress 的三个常用命令

6. 什么是 Cloudflare Pages？

Cloudflare 是什么？

为什么选 Cloudflare Pages？

自动部署原理

7. 搭建全过程回顾

准备环境

创建项目

配置网站

写文章

初始化和推送 Git

配置 SSH Key

部署到 Cloudflare Pages

最终效果

8. 知识地图

9. 常用命令速查