适合谁看：完全没接触过建站、没写过后端代码的新手。
看完能得到什么：一个属于自己的博客网站，可以用自己的域名访问，写作只用写 Markdown，图片粘贴即上传。
预计耗时：认真的话 2～4 小时（大部分时间在下载和注册上）。

本文所有命令都一步一步给全，你只要照着敲就行。遇到没见过的名词别慌，我都在旁边解释了。

0. 写在前面

0.1 这套方案长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
你的电脑（写作 + 本地预览）
   │
   │  git push（推送源代码）
   ▼
GitHub 仓库（存放博客源码，相当于云端网盘 + 版本管理）
   │
   │  自动触发构建
   ▼
Cloudflare Pages（自动跑 hexo generate，生成静态网页并托管）
   │
   │  绑定自定义域名
   ▼
你的免费域名（xxxx.localhost.cc）→ 访客访问

图片走另一条线：
本地图片 → PicGo 自动上传到 GitHub 图床仓库 → 生成 CDN 链接 → 插进文章里

用人话解释每个零件是干嘛的：

零件 作用 花钱吗
Hexo 把 Markdown 文章「编译」成网页的工具 免费
Butterfly 博客的「皮肤」，决定长什么样 免费
Node.js Hexo 的运行环境，必须装 免费
Git 把代码传到 GitHub 的工具 免费
GitHub 存放博客源码的仓库 免费
Cloudflare Pages 自动构建 + 全球托管你的网页 免费
localhost.cc 提供免费二级域名，让网址好看 免费
PicGo 图片一键上床到图床，自动复制链接 免费

0.2 开始前请确认

  • 有一台能上网的电脑（本文以 Windows 为例，Mac / Linux 会额外标注差异）
  • 有一个能收邮件的邮箱（建议用 163 / QQ / Gmail）
  • 能正常访问 GitHub（如果打不开，见第十四节的网络排查）
  • 电脑有约 2 GB 空闲磁盘

0.3 本文使用的版本（2026 年 11 月）

软件 版本 备注
Node.js 24 LTS 或 26 LTS Hexo 8 要求 Node ≥ 20.19.0，别装太老的版本
Git 2.5x 安装最新版即可
Hexo 8.1.2
hexo-theme-butterfly 5.7.2
PicGo 3.0.3

💡 提示：软件版本会更新，命令基本不变。如果看到比我写的更新的版本号，直接装新的就好。

一、注册 GitHub 账号

GitHub 既是账号系统，也是仓库（存代码的地方）。后面 Cloudflare 需要读你的 GitHub 仓库。

  1. 打开 https://github.com/signup
  2. 输入邮箱 → 设置密码（建议 12 位以上，大小写+数字）→ 起一个用户名
    • 用户名会出现在网址里，例如 zhangsan，建议用英文小写 + 数字，别用奇怪符号
  3. 完成滑块验证 → 输入邮箱收到的 8 位验证码
  4. 进入 GitHub 后，点右上角头像 → Settings → 左侧 Emails，确认邮箱状态是 Verified
  5. （强烈建议）同页面左侧 Password and authentication → 开启 Two-factor authentication (2FA)
    用手机上的验证器 App（如 Microsoft Authenticator / Google Authenticator）扫码即可

    ⚠️ 开启 2FA 后会给你一组恢复码，请抄到纸上或存进密码管理器。丢了恢复码 = 账号救不回来。

二、安装 Git

2.1 下载安装

  1. 打开 https://git-scm.com/download/win，下载 64-bit Git for Windows Setup
  2. 双击安装，一路 Next 即可。中途有几个选项值得注意：
安装页面 建议选择 为什么
Default editor 选 Use Visual Studio Code 或保持 Vim 弹出编辑说明文字时用得上
Adjusting your PATH Git from the command line and also from 3rd-party software（默认） 这样命令行才能用 git
HTTPS transport Use the native Windows Secure Channel library（默认） 走系统证书，国内更稳
Line ending conversions Checkout Windows-style, commit Unix-style（默认） 避免换行符导致的诡异 diff
Credential helper Git Credential Manager（默认） 以后 push 会自动弹窗登录，不用每次输密码
  1. 安装完成后，关掉所有已经打开的命令行窗口（重要！PATH 才会生效）

2.2 验证安装

按 Win + R，输入 cmd 回车，然后输入：

1
git --version

看到类似 git version 2.5x.x.windows.1 就成功了。

2.3 配置身份（必做）

Git 需要知道「这次提交是谁干的」，把下面两行里的内容换成你自己的：

1
2
git config --global user.name "zhangsan"
git config --global user.email "你的GitHub邮箱@example.com"

顺手再加两条，能让中文文件名不乱码、命令行更好看：

1
2
git config --global core.quotepath false
git config --global init.defaultBranch main

检查配置：

1
git config --global --list

⚠️ 注意：user.email 最好填 GitHub 上验证过的邮箱，否则 GitHub 里提交记录不会显示你的头像（不影响推送）。

三、安装 Node.js

Hexo 是跑在 Node.js 上的，所以 Node.js 必须先装好。

3.1 选版本

打开 https://nodejs.org/zh-cn/download，下载 LTS（长期支持版），推荐：

  • Node.js 24 LTS（最稳，推荐新手）
  • 或 Node.js 26 LTS（更新）

⚠️ 不要去装 Node 18 / 20。Hexo 8 要求 Node ≥ 20.19.0，装旧版会报 Unsupported engine 之类的错误。
不要下载 Current（奇数版本，如 25/27），那是给尝鲜的人用的。

3.2 安装（Windows）

  1. 下载 .msi 安装包（如 node-v24.x.x-x64.msi）
  2. 双击 → 一路 Next → 勾选 Add to PATH（默认就是勾上的）→ Install
  3. 装完重新打开 cmd，验证：
1
2
node -v
npm -v

分别输出 v24.x.x 和 11.x.x 之类的版本号就 OK。

3.3 （可选但推荐）换个国内镜像，快很多

1
npm config set registry https://registry.npmmirror.com

想换回官方源：

1
npm config set registry https://registry.npmjs.org

3.4 Mac / Linux 用户

Mac 用 Homebrew 最省事：

1
brew install node

Linux（Ubuntu/Debian）用 NodeSource 或发行版自带包都可以，只要能保证 node -v ≥ 20.19。

💡 多版本管理：如果以后要在多个 Node 版本间切换，Windows 用 nvm-windows，Mac/Linux 用 nvm。新手可以先不折腾。

四、安装 Hexo 并创建本地博客

4.1 安装 Hexo 命令行工具

在 cmd（或 PowerShell）里执行：

1
npm install -g hexo-cli

验证：

1
hexo -v

如果提示 'hexo' 不是内部或外部命令，说明 npm 的全局目录不在 PATH 里。
先执行 npm config get prefix 看看路径，再把它加到系统的环境变量 Path 中，然后重开命令行。
实在搞不定就用 npx hexo 代替 hexo，效果一样。

4.2 创建博客文件夹

先进入你想放博客的位置。建议路径里不要有中文和空格，例如 D:\blog：

1
2
3
d:
mkdir blog
cd blog

然后初始化（myblog 是文件夹名，可以改成你喜欢的）：

1
2
3
hexo init myblog
cd myblog
npm install

⚠️ 注意：hexo init 需要从 GitHub 下载初始模板，国内可能失败。
失败的话多试几次，或者先设好 3.3 的镜像 + 给 git 挂代理：

1
git config --global http.proxy http://127.0.0.1:7890

（端口换成你自己代理的端口，用完记得 --unset）

4.3 认识一下目录结构

1
2
3
4
5
6
7
8
9
10
myblog/
├── _config.yml          ← 站点总配置（标题、网址、时间等）
├── package.json         ← 记录了博客依赖了哪些东西
├── scaffolds/           ← 新建文章的模板
├── source/
│   ├── _posts/          ← ✨ 你的文章全部放这里（Markdown 文件）
│   ├── _drafts/         ← 草稿
│   └── about/           ← 关于页面等
├── themes/              ← 主题目录（后面 Butterfly 会装在这里或 node_modules）
└── public/              ← 生成出来的静态网页（不用手动改，可随时删）

4.4 本地先跑起来看看

1
2
3
hexo clean
hexo generate
hexo server

浏览器打开 http://localhost:4000，能看到 Hexo 默认主题的首页，说明环境全通了。

Ctrl + C 可以停掉服务。

💡 调试时建议一直开着 hexo server，改了文章它会自动刷新。如果 4000 端口被占用，换端口：hexo server -p 5000。

五、安装 Butterfly 主题

5.1 装主题（重要：用 npm 装，不要 git clone）

在博客根目录 myblog 下执行：

1
npm install hexo-theme-butterfly

为什么强烈建议用 npm 而不是 git clone 到 themes/？

  • themes/butterfly 目录如果没被 git 跟踪（或被 .gitignore 忽略），Cloudflare 云端构建时会找不到主题，直接报错；
  • 用 npm 安装后，主题名字会写进 package.json，云端执行 npm install 时能自动装好，彻底避免「本地正常、线上构建失败」这个新手头号大坑。

如果你已经在用 git clone 方式，也不用重来：只要确认主题文件已经提交到 GitHub 仓库（或用 submodule）即可。

5.2 应用主题

用记事本或 VS Code 打开根目录的 _config.yml，找到 theme: 那一行，改成：

1
theme: butterfly

⚠️ YAML 格式很挑：冒号后面必须有一个空格，不要用 Tab 缩进。

5.3 安装渲染器插件（保险起见）

Butterfly 的页面用 pug 和 stylus 写的，正常情况 npm 会自动带上。为防报错，手动装一遍：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

5.4 建立主题专属配置文件（关键一步）

不要直接改 node_modules 里的配置，主题一升级你的心血就没了。正确姿势是在博客根目录建一个 _config.butterfly.yml：

Windows（PowerShell）：

1
Copy-Item node_modules\hexo-theme-butterfly\_config.yml _config.butterfly.yml

Mac / Linux：

1
cp node_modules/hexo-theme-butterfly/_config.yml _config.butterfly.yml

以后所有主题相关的配置只改根目录的 _config.butterfly.yml。Hexo 会自动把它和主题自带的 _config.yml 合并，同名项以你的文件为准。

5.5 看看效果

1
2
hexo clean
hexo server

刷新 http://localhost:4000，应该已经变成 Butterfly 的卡片风界面了。

❗ 如果页面上出现一堆 extends includes/layout.pug 之类的源代码文字，说明渲染器没装好，回到 5.3 重装一次再 hexo clean。

六、主题基础配置：让它变成「你的」博客

配置文件有点长，新手只需要改下面这几处，其他保持默认。

6.1 站点配置 _config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 网站标题
title: 我的博客
# 副标题
subtitle: '记录，然后成长'
# 网站描述（SEO 用）
description: '一名普通人的学习笔记与技术分享'
# 关键词
keywords: 博客,学习笔记
# 作者名
author: zhangsan
# 语言（简体中文）
language: zh-CN
# 时区，不设置的话文章日期可能差 8 小时
timezone: 'Asia/Shanghai'

# ⚠️ 上线后一定要改成你的真实域名，否则分享链接、RSS、站点地图全是错的
url: https://blog.localhost.cc
# 文章链接格式（保持默认即可）
permalink: :year/:month/:day/:title/

# 让文章支持子文件夹放图片（可选）
post_asset_folder: false

6.2 主题配置 _config.butterfly.yml

① 导航菜单

1
2
3
4
5
6
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  关于: /about/ || fas fa-user

② 头像和首页大图

1
2
3
4
5
6
avatar:
  img: /img/avatar.png   # 把图片放到 source/img/ 下，这里写 /img/xxx.png
  effect: true           # 头像转圈特效

# 首页顶部大图（留空则用主题默认图）
index_img: /img/home.png

③ 打字机副标题

1
2
3
4
5
6
7
subtitle:
  enable: true
  effect: true
  source: false
  sub:
    - 今天也要好好写代码
    - 记录生活的每一刻

④ 暗色模式 & 目录

1
2
3
4
5
6
7
8
darkmode:
  enable: true
  button: true

toc:
  enable: true      # 文章右侧显示目录
  number: true
  style: ocean

⑤ 本地搜索（不用外部服务，推荐开）

1
2
3
4
local_search:
  enable: true
  preload: true
  CDN:

⑥ 页脚

1
2
3
4
5
footer:
  owner:
    enable: true
    since: 2026
  custom_text: 本站使用 Hexo + Butterfly 搭建

⑦ 想加自己的 CSS / JS

1
2
3
4
5
inject:
  head:
    # - <link rel="stylesheet" href="/css/custom.css">
  bottom:
    # - <script src="/js/custom.js"></script>

⚠️ 提醒：_config.butterfly.yml 里 enable 这类开关只认 true / false（小写），写 True 或 yes 有时会不生效。

6.3 创建「标签 / 分类 / 关于」页面

菜单里链接的页面默认是不存在的，需要手动建。在博客根目录依次执行：

1
2
3
hexo new page tags
hexo new page categories
hexo new page about

然后分别打开 source/tags/index.md、source/categories/index.md，把开头的 type 改成对应类型。以标签页为例：

1
2
3
4
5
6
---
title: 标签
date: 2026-11-08 09:00:00
type: tags
comments: false
---

分类页写 type: categories，关于页写 type: about（或直接当普通页面写自我介绍）。

再执行一次：

1
2
hexo clean
hexo server

点菜单里的「标签 / 分类」，不再 404 就对了。

七、写第一篇文章

7.1 新建文章

1
hexo new "我的第一篇文章"

会在 source/_posts/ 下生成 我的第一篇文章.md，打开它，顶部是这样的：

1
2
3
4
5
6
---
title: 我的第一篇文章
date: 2026-11-08 09:00:00
tags:
categories:
---

下面是正文，用 Markdown 写就行。

7.2 常用 Front-matter 字段

字段 作用 示例
title 文章标题 我的第一篇博客
date 发布时间 2026-11-08 09:00:00
updated 更新时间（可省） 同上
tags 标签，可多个 [Hexo, 教程]
categories 分类，可多个层级 [建站教程]
cover 文章封面图 /img/cover.png
top_img 文章顶部大图 /img/top.png
description 摘要（首页显示） 这篇文章讲……
toc 是否显示目录 true / false
comments 是否开评论 true / false

7.3 常用命令速查

命令 作用
hexo new "标题" 新建文章
hexo new page 名字 新建页面
hexo clean 清缓存（改配置没生效时先来一发）
hexo generate（简写 hexo g） 生成静态网页
hexo server（简写 hexo s） 本地预览 http://localhost:4000
hexo deploy（简写 hexo d） 部署（本方案用不到，见第十一节附注）

💡 小技巧：Markdown 插入图片的语法是 ![图片描述](图片链接)。图片链接怎么来？往下看第十二节的 PicGo。

八、注册免费域名（localhost.cc）

⚠️ 先说明：免费二级域名服务的前端界面经常改版，而且我这里无法登录它的控制台，所以下面是这类服务的通用流程，具体按钮名字以你看到的页面为准。核心逻辑一定是：注册账号 → 申请一个好记的子域名 → 在它的 DNS 面板里添加记录。

8.1 为什么需要它

Cloudflare Pages 会免费送你一个 xxx.pages.dev 的网址，能直接用。但 https://myblog.pages.dev 不够好记，用免费二级域名就能变成 https://myblog.localhost.cc。

8.2 通用注册步骤

  1. 打开 https://localhost.cc/，点 注册 / Sign up
  2. 填邮箱 + 密码，去邮箱点验证链接激活账号
  3. 登录后找到 注册域名 / 申请域名 / New Domain 之类的入口
  4. 输入你想要的前缀，比如 myblog，系统会检查是否被占用
  5. 提交后进「我的域名 / DNS 管理」页面，你会看到两个东西：
    • 域名本身：myblog.localhost.cc
    • DNS 记录管理区：可以添加 A / CNAME / TXT 等记录
  6. 先记下这个域名，第十一节要用

8.3 注意事项（一定看）

  • ⚠️ 免费域名随时可能失效。服务商倒闭、政策调整、长期不登录都可能收回。建议只当过渡用，认真做站的话迟早买个自己的域名（.com 一年几十块）。
  • ⚠️ 不要在免费域名上做涉及金钱、登录的正式业务，搜索引擎信任度低，也容易被墙。
  • ⚠️ 记录保存好：域名、注册邮箱、DNS 面板地址。
  • ✅ 这类服务通常只能改 DNS 记录，不能改 NS（名称服务器）。这没关系——Cloudflare Pages 支持「子域名用 CNAME 接入」，不需要把域名托管到 Cloudflare（见 11.5）。
  • ✅ 如果注册页面打不开或一直失败，可以直接跳过这一节，先用 xxx.pages.dev 把流程跑通，之后再换域名。

九、注册并配置 Cloudflare

Cloudflare 负责三件事：免费 CDN 加速、自动 HTTPS 证书、以及自动构建部署我们的博客。

9.1 注册

  1. 打开 https://dash.cloudflare.com/sign-up
  2. 填邮箱 + 密码（密码强度要求高，建议直接用密码管理器生成）
  3. 去邮箱点验证链接
  4. 登录后如果提示选择套餐，选 Free（免费版）

9.2 要不要把域名「接入」Cloudflare？

看你想要哪种玩法：

方式 适用场景 要做的事
方式 A：只做子域 CNAME（推荐给免费域名用户） myblog.localhost.cc 指向 Pages 不用把域名加进 Cloudflare，直接去域名商的 DNS 面板加一条 CNAME
方式 B：整站托管到 Cloudflare（NS 接入） 你自己买的域名，想用 Cloudflare 的全套功能 在 Cloudflare 添加站点 → 拿到两个 NS → 改到域名商 → 等生效

方式 B 的操作（如果你以后买了自己的域名）：

  1. Cloudflare 控制台 → 添加域 / Add a domain
  2. 输入你的域名 → 选 Free 套餐
  3. Cloudflare 会给你两个名称服务器，形如：
    • xxx.ns.cloudflare.com
    • yyy.ns.cloudflare.com
  4. 到域名商（阿里云/腾讯云/Namesilo 等）的域名管理里，把 NS 换成这两个
  5. 回 Cloudflare 点「我已更新名称服务器」，等几分钟到 24 小时生效

💡 免费二级域名（如 localhost.cc）基本不支持改 NS，所以走方式 A 就好，完全不影响 Pages 部署。

十、把博客源码推送到 GitHub

10.1 新建仓库

  1. 登录 GitHub → 右上角 + → New repository
  2. Repository name 填 myblog（随便起，但建议和文件夹一致）
  3. Description 可留空
  4. 可见性选 Public 或 Private 都行
    • Public：免费、构建速度快，但你的文章源码公开
    • Private：Cloudflare Pages 同样支持，但需要授权 Cloudflare 访问私有仓库
  5. 不要勾选 Add a README file、.gitignore、license（我们要用本地的文件）
  6. 点 Create repository，复制它给你的仓库地址，形如 https://github.com/zhangsan/myblog.git

10.2 确认 .gitignore 没问题

hexo init 已经生成好 .gitignore，打开确认里面有这些（没有就补上）：

1
2
3
4
5
6
7
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/

⚠️ 千万别把 node_modules/ 提交上去（几万个文件，推送到一半必然失败）。
但 package.json 和 package-lock.json 必须提交，云端靠它们安装依赖。

10.3 推送

在博客根目录 myblog 下依次执行：

1
2
3
4
5
6
git init
git add .
git commit -m "初始化博客"
git branch -M main
git remote add origin https://github.com/你的用户名/myblog.git
git push -u origin main

第一次 push 会弹出 GitHub 登录窗口（Git for Windows 自带的 Git Credential Manager），
选 Sign in with your browser，浏览器里点授权即可。

⚠️ 如果提示 remote origin already exists，说明之前加过，改用：

1
git remote set-url origin https://github.com/你的用户名/myblog.git

⚠️ 如果卡在输入用户名密码并且怎么都不对：GitHub 早就不支持账号密码推送了，得用 Personal Access Token（见 12.3）当密码，或者走上面的浏览器授权。

推送成功后刷新 GitHub 页面，应该能看到你的文件列表（但看不到 node_modules 和 public，这是对的）。

十一、Cloudflare Pages 部署 + 绑定域名

这是最爽的一步：以后你只管 git push，网页自动更新。

11.1 创建 Pages 项目

  1. Cloudflare 控制台 → 左侧 Workers 和 Pages（Workers & Pages）
  2. 点 Create application（创建应用） → 切到 Pages 选项卡
  3. 点 Import an existing Git repository（导入现有 Git 仓库）
  4. 首次使用要授权：选 GitHub → 同意授权 → 可以选择「只授权某个仓库」更安全
  5. 在列表里选中你的 myblog 仓库 → Begin setup

11.2 填构建设置（照抄）

配置项 填什么
Production branch（生产分支） main
Build command（构建命令） npm run build
Build output directory（输出目录） public

💡 npm run build 是 hexo init 生成的脚本，等价于 hexo generate。写 hexo generate 也行，但 npm run build 更稳。

11.3 设置 Node 版本（必做，否则可能构建失败）

在同一个页面往下拉，展开 Environment variables（环境变量），添加：

变量名 值
NODE_VERSION 24

⚠️ 不加这一条，云端可能用旧版 Node 构建，报 Unsupported engine 或直接失败。Hexo 8 要求 Node ≥ 20.19.0，写 24 最稳。

11.4 开始部署

点 Save and Deploy（保存并部署），然后就是等。第一次大概 1～3 分钟，你会看到日志里依次出现：

1
2
3
4
5
Cloning repository...
Installing dependencies...   ← npm install
Executing build command...   ← npm run build（hexo generate）
Uploading... 
Success! Your site is live at https://myblog-xxx.pages.dev

点开 https://myblog-xxx.pages.dev，你的博客就上线了！🎉

以后怎么更新？ 本地改完文章后：

1
2
3
git add .
git commit -m "新增文章：我的第一篇文章"
git push

Cloudflare 检测到推送 → 自动重新构建 → 一分钟左右网站更新。完全不用手动上传文件。

11.5 绑定你的免费域名

按 Cloudflare 官方说明，子域名不需要把域名托管到 Cloudflare，加 CNAME 就行：

  1. Cloudflare → 你的 Pages 项目 → 自定义域 / Custom domains → Set up a domain
  2. 输入 myblog.localhost.cc → Continue
  3. 会提示需要添加 DNS 记录，记录内容是你的 myblog-xxx.pages.dev
  4. 去 localhost.cc 的 DNS 管理面板，添加一条记录：
类型 主机记录 / Name 记录值 / Content TTL
CNAME myblog myblog-xxx.pages.dev 自动 / 600
  1. 回 Cloudflare 点 Check DNS records（检查 DNS） / 激活
  2. 等几分钟（DNS 生效），访问 https://myblog.localhost.cc 就能打开了

⚠️ 顺序很重要：必须先在 Pages 里添加自定义域，再去 DNS 加 CNAME。反过来做会报 522 错误（因为 Cloudflare 不知道该域名归哪个 Pages 项目）。

⚠️ HTTPS 证书需要几分钟到几小时自动签发。刚绑定时提示「不安全」是正常的，耐心等。

⚠️ 如果一直提示「等待 DNS 生效」，检查 CNAME 值有没有多打空格、有没有漏掉 .pages.dev。

11.6 （可选）关闭 pages.dev 访问 / 强制 HTTPS

  • 想让访客只能用你的域名：Pages → 自定义域 里可以设置重定向策略，或用账户级的 Bulk Redirect 把 *.pages.dev 跳到你的域名。
  • 强制 HTTPS：Cloudflare → 你的域名 → SSL/TLS → Edge Certificates → 打开 Always Use HTTPS。

💡 免费额度：Pages 免费版每月约 500 次构建、静态资源请求和带宽不限量（以官方为准）。个人博客完全够用。

11.7 附：不想用 Cloudflare Pages 的话（GitHub Pages 备选方案）

如果你只想部署到 GitHub Pages：

1
npm install hexo-deployer-git --save

然后在 _config.yml 里加：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main

之后每次写完文章执行：

1
hexo clean && hexo generate && hexo deploy

再在仓库 Settings → Pages 里把 Source 选到对应分支。

但我推荐 Cloudflare Pages：构建在云端、不占用你本地网络、自带全球 CDN 和自动 HTTPS，图片挂 GitHub 也不会把博客拖慢。

十二、PicGo 图床：让图片粘贴即上传

12.1 为什么需要图床

Hexo 默认把图片放在本地文件夹里，问题是：图片会跟代码一起提交，仓库越来越胖，而且 Cloudflare Pages 每次构建都要传一遍，速度慢。

用「图床」的思路是：图片单独存到一个仓库（或对象存储），通过 CDN 链接引用。文章里只留一行链接，又轻又快。

12.2 下载安装 PicGo

一路 Next 装完，打开 PicGo，你会看到左侧是图床列表，右侧是上传区。

12.3 创建一个专门存图片的 GitHub 仓库 + Token

① 建仓库

GitHub → + → New repository → 名字填 blog-images → Public（重要，私有仓库的图外链会 403）→ Create。

可以勾选 Add a README file，这样仓库不是空的。

❓ 为什么一共要建两个仓库？

到这一步你会有两个 GitHub 仓库，各干各的活：

仓库 存什么 谁在用
myblog 博客源码（文章 Markdown、配置、主题设置） Cloudflare Pages 每次构建时拉取
blog-images 只存图片 PicGo 上传图片，jsDelivr 提供 CDN 加速

分开的好处：博客仓库永远只有几十 KB 的文本，构建又快又不容易失败；图片走 CDN，不占博客仓库、也不拖慢网页。

如果混在一个仓库里，每次发文章都要把一堆图片一起提交，仓库会迅速膨胀到几百 MB，Cloudflare 每次构建都得重新下载一遍——这就是图片要单独放的原因。

嫌麻烦的替代方案（也完全可以，只是体验差一点）：

  • 方案一：只用一个仓库。PicGo 的「设定仓库名」也填 myblog，存储路径填 source/img/。这样图片会跟着博客一起发布，链接写作 /img/xxx.png。缺点是仓库变大、PicGo 上传会频繁产生 commit，且和文章提交容易撞车。
  • 方案二：图片放本地。干脆不用 PicGo，图片直接丢进 source/img/ 文件夹，文章里写 ![](/img/xxx.png)。最简单，但博客源码里会堆满图片。

② 生成 Token（访问令牌）

  1. GitHub → 右上角头像 → Settings
  2. 左侧拉到最下 → Developer settings
  3. Personal access tokens → 选 Tokens (classic) → Generate new token (classic)
  4. 填写：
项目 填什么
Note picgo-blog-images
Expiration No expiration（或 90 天，到期要重新生成）
Scopes 只勾 repo（它包含读写仓库内容的权限）
  1. 点 Generate token，页面上会出现一串 ghp_xxxxxxxxxxxx
  2. 立刻复制保存！离开页面后就再也看不到这串字符了

⚠️ Token 等于你仓库的钥匙，泄露了别人就能改你的仓库。不要发到群里、不要写进文章、不要提交到 Git。
⚠️ 如果你用的是 Fine-grained token，权限要设为 Contents: Read and write，并且仓库范围选中 blog-images。

12.4 在 PicGo 里配置 GitHub 图床

PicGo 左侧点 图床设置 / PicGo Settings → GitHub，按下表填写：

字段 填写内容 说明
图床配置名 github 随便起，方便区分
设定仓库名 zhangsan/blog-images 格式必须是 用户名/仓库名
设定分支名 main 新仓库默认是 main，老仓库可能是 master
设定Token ghp_xxxxxxxx 粘贴 12.3 生成的那串
指定存储路径 images/ 图片会存进 images 文件夹，结尾的斜杠别丢
设定自定义域名 https://cdn.jsdelivr.net/gh/zhangsan/blog-images@main 见下方说明

点 确定，再点 设为默认图床。

关于自定义域名：

  • 不用 CDN 直接填 https://raw.githubusercontent.com/zhangsan/blog-images/main
    → 但 raw.githubusercontent.com 在国内基本打不开，你的访客看不到图。
  • 推荐用 jsDelivr 免费 CDN：
    1
    https://cdn.jsdelivr.net/gh/用户名/仓库名@分支名
    注意结尾不要加斜杠，PicGo 会自动拼上 images/xxx.png。

⚠️ jsDelivr 在国内偶尔抽风。如果图片加载不出来，可以换：

  • 自己的 Cloudflare R2 / 对象存储 + 自定义域名（最稳，见 12.7）
  • 其他 GitHub 加速域名（稳定性参差不齐，自己测试）

⚠️ jsDelivr 有缓存。同名图片覆盖上传后可能还是旧图，改个文件名，或者在链接里加 ?v=2。

12.5 测试上传

  1. 随便截个图（Win + Shift + S）复制到剪贴板
  2. PicGo 里点 剪贴板图片 或按快捷键 Ctrl + Shift + P
  3. 上传成功后 PicGo 会自动把链接复制到剪贴板（默认就是 Markdown 格式）
  4. 到 GitHub 的 blog-images 仓库看看，应该有 images/xxxx.png 了

💡 如果想把复制格式固定成 Markdown，去 PicGo 设置 → 上传后复制的格式 里选 Markdown。

12.6 写文章时怎么用

直接在 Markdown 里粘贴：

1
![截图说明](https://cdn.jsdelivr.net/gh/zhangsan/blog-images@main/images/20261108-abc.png)

Butterfly 会自动渲染。想让图片支持点击放大（灯箱效果），Butterfly 默认已开启，不用额外配置。

💡 进阶：PicGo 还能和 Typora、VS Code 联动。

  • Typora：文件 → 偏好设置 → 图像 → 插入图片时选「上传图片」→ 上传服务选 PicGo(app) → 填 PicGo 的安装路径。
  • VS Code：装 PicGo 插件，配置里把 picgo.path 指向 PicGo 可执行文件。
    这样截图后直接粘贴，图片自动上传并插入链接，写作体验起飞。

12.7 （可选）更稳的图床：Cloudflare R2

如果 jsDelivr 经常挂，可以考虑 Cloudflare 自家的对象存储 R2（有免费额度，约 10 GB 存储 + 免费出网）：

  1. Cloudflare 控制台 → R2 → 创建存储桶（Bucket），例如 blog-img
  2. 给存储桶绑定一个自定义域名（如 img.localhost.cc）
  3. 生成 R2 的 Access Key / Secret Key
  4. PicGo 里安装插件 picgo-plugin-s3，用 S3 兼容方式填写 R2 的 endpoint、桶名、密钥
  5. 自定义域名填 https://img.localhost.cc

这样上传完的链接形如 https://img.localhost.cc/images/xxx.png，全程走 Cloudflare，速度和稳定性都更好。

十三、日常写作与发布流程

13.1 标准流程（记住这五步就够）

1
2
3
4
5
1. hexo new "文章标题"        → 生成 Markdown 文件
2. 用 Typora / VS Code 写文章  → 截图粘贴，PicGo 自动上传
3. hexo server               → 本地预览 localhost:4000 看效果
4. git add . && git commit -m "新增文章" && git push
5. 等 Cloudflare 自动构建完成 → 刷新网站，收工 🎉

13.2 一键发布脚本

在博客根目录新建文件 发布.bat（Windows），内容：

1
2
3
4
5
6
7
8
9
10
11
12
@echo off
chcp 65001 >nul
cd /d %~dp0
git add .
git commit -m "更新博客 %date% %time%"
git push
echo.
echo ====================================
echo  推送完成，Cloudflare 正在构建...
echo  大约 1~2 分钟后刷新你的网站
echo ====================================
pause

以后写完文章，双击这个文件就发布完了。

Mac / Linux 用 publish.sh：

1
2
3
4
5
6
#!/bin/bash
cd "$(dirname "$0")"
git add .
git commit -m "更新博客 $(date '+%Y-%m-%d %H:%M:%S')"
git push
echo "推送完成，Cloudflare 正在构建..."

给执行权限：chmod +x publish.sh

13.3 几个效率小技巧

  • 草稿模式：hexo new draft "想法" 存草稿，预览用 hexo server --draft，写好后 hexo publish "想法" 转正。
  • 本地图床备份：PicGo 的图床仓库建议定期 git clone 一份到本地，防止哪天误删。
  • 文章备份：博客仓库本身就是备份，别忘了 git push。
  • 想换电脑写作：新电脑装好 Git + Node → git clone 博客仓库 → npm install → 继续写。

十四、常见问题 FAQ

现象 原因 解决
页面显示一堆 extends includes/layout.pug pug/stylus 渲染器没装 npm install hexo-renderer-pug hexo-renderer-stylus --save，再 hexo clean
'hexo' 不是内部或外部命令 npm 全局路径没进 PATH 把 npm config get prefix 的路径加进环境变量，或用 npx hexo
Cloudflare 构建报 hexo: not found 构建命令写成了裸 hexo 改成 npm run build
构建报 Cannot find module 'hexo-theme-butterfly' 主题是 git clone 到 themes/ 的，但也装在 node_modules 或没提交 改用 npm install hexo-theme-butterfly 并把 package.json 提交
构建报 Node 版本错误 云端 Node 太旧 环境变量加 NODE_VERSION = 24
构建成功但页面是默认主题 _config.yml 里 theme: 没改或拼错 改成 theme: butterfly（注意空格）
本地正常，线上样式全乱 url 没改成真实域名 / CDN 被墙 改 _config.yml 的 url，主题配置里换 CDN 源
图片不显示 仓库是 Private / 链接错 / jsDelivr 抽风 图床仓库设为 Public，检查链接，换 CDN
改了配置线上没变化 浏览器缓存或没推送 Ctrl + F5 强刷、hexo clean、确认 git push 成功
推送报 403 或认证失败 Token 过期 / 权限不足 重新生成 repo 权限的 Token
推送报 failed to push some refs 远程有你本地没有的提交 先 git pull --rebase origin main 再 push
中文文件名显示成 \344\275\240 Git 转义中文 git config --global core.quotepath false
4000 端口被占用 有其他程序在用 hexo server -p 5000
文章日期差 8 小时 时区没设 _config.yml 里加 timezone: 'Asia/Shanghai'
免费域名突然打不开 域名被回收 / DNS 变了 换域名或买正式域名，回 11.5 重新绑定
访问报 522 先加 CNAME 后加自定义域 顺序反了，删掉 DNS 记录，先在 Pages 加自定义域再配 DNS
评论功能没显示 没配置评论系统 新手可先 comments: false 关掉；要开推荐 Twikoo / Waline，需另行部署

十五、注意事项汇总（重要程度从高到低）

🔴 必须注意

  1. 主题用 npm 安装，不要 git clone。这是新手线上构建失败的第一大原因。
  2. Cloudflare Pages 的环境变量 NODE_VERSION 一定要设（写 24），并且构建命令用 npm run build、输出目录填 public。
  3. _config.yml 的 url 上线后必须改成真实域名，否则分享卡片、RSS、sitemap 全是错的。
  4. Token / 密码 / 恢复码不要提交到 GitHub，也不要写进文章。PicGo 的 Token 只存在你本机。
  5. 绑定域名的顺序：先在 Pages 添加自定义域 → 再去 DNS 加 CNAME。反了必 522。

🟡 建议注意

  1. 只改根目录的 _config.butterfly.yml，不要改 node_modules 里的配置，否则主题一升级全部丢失。
  2. node_modules/ 和 public/ 不要提交，但 package.json + package-lock.json 必须提交。
  3. YAML 格式：冒号后有空格、不用 Tab、true/false 小写。
  4. 路径别带中文和空格（D:\blog 比 D:\我的东西\博客 项目 省一百个麻烦）。
  5. 免费域名有失效风险，重要内容记得留本地备份，条件成熟就换正式域名。
  6. 图片仓库设 Public，私有仓库的图片外链会 403。
  7. jsDelivr 有缓存，换图记得改文件名或加 ?v=2。

🟢 体验优化

  1. 开启 GitHub 2FA，保护好账号。
  2. 本地 hexo server 常开，改完立刻看效果。
  3. 用 Typora / VS Code + PicGo 联动，写作效率翻倍。
  4. 文章写好后检查一遍 Front-matter，tags 和 categories 写对了才能正常归类。
  5. 定期 git pull 同步仓库，换电脑无缝衔接。
  6. 关于备案：Cloudflare Pages 服务器在境外，不需要 ICP 备案；但国内访问速度一般，介意的话可以之后再考虑国内服务器 + 备案。

十六、上线检查清单

全部打勾，你的博客就是完全体了 ✅

  • GitHub 账号注册完成，邮箱已验证，2FA 已开启
  • Git 安装完成，user.name / user.email 已配置
  • Node.js 安装完成（≥ 20.19），node -v 正常
  • hexo init 成功，hexo server 能打开 localhost:4000
  • Butterfly 主题已用 npm 安装，theme: butterfly 已设置
  • 已创建根目录 _config.butterfly.yml
  • 站点标题、作者、url、timezone 已改
  • 导航菜单、头像、副标题已配好
  • 标签 / 分类 / 关于页面已创建且不 404
  • 至少发了一篇文章
  • 代码已 git push 到 GitHub，node_modules 没被提交
  • Cloudflare Pages 项目创建成功，NODE_VERSION=24 已设置
  • xxx.pages.dev 能正常访问
  • 自定义域名已在 Pages 添加，DNS 的 CNAME 已配置并生效
  • HTTPS 证书已签发，https:// 正常访问
  • PicGo 安装并配置好 GitHub 图床，上传测试成功
  • 文章中插入的图片能正常显示
  • 写好了发布脚本，知道以后怎么更新博客

最后一句：搭博客最难的是第一次，跑通一次之后你会发现——以后发博客就只剩「写文章 + 双击发布脚本」两件事了。
祝你写得开心，也别忘了：内容才是博客的主角，皮肤只是衣服。 🎈