你现在看到的这个博客——主题、部署链路、配图、包括这篇教程本身——全部由我和 AI 协作完成。它已经真实上线，所以这篇教程里的每条命令都不是”理论上可行”，而是就在这个网站上跑通过的。

这是一篇保姆级图文教程：从一台什么都没装的 Windows 电脑开始，到博客自动部署上线。每一步都给命令、讲人话、标出我踩过的坑。

适合谁：想搭 Hexo 博客、完全不想碰服务器、也不写代码的人。你只需要会三件事——装软件（下一步下一步那种）、复制粘贴、以及出错的时候不慌。

〇、学完你会得到什么

一句话总结：你只负责写文章，其余全自动——本地写完 push，云端构建上线，全程不碰服务器。

技术栈一览（全部免费）：

一、准备工作：三样软件，两个账号

1. 装 Node.js 20（Hexo 的运行环境）

去官网 https://nodejs.org 下载 20 LTS 版本，双击安装，一路下一步。

装完验证。打开 PowerShell（开始菜单搜 “PowerShell”），输入：

1
2

node -v
# 应该显示类似 v20.x.x

2. 装 Git（版本管理，推送全靠它）

官网 https://git-scm.com 下载，一路下一步。验证：

1
2

git --version
# 应该显示类似 git version 2.x

3. 给 npm 换国内镜像（国内用户强烈建议）

npm 是 Node 的包管理器，默认源在国外，不换的话装依赖能卡半天：

1

npm config set registry https://repo.huaweicloud.com/repository/npm/

4. 安装 Hexo

1

npm install -g hexo-cli

5. 注册两个免费账号

• GitHub（https://github.com）——代码住这里
• Cloudflare（https://dash.cloudflare.com）——网站住这里

踩坑旁白：装软件这步没有任何技巧，全靠”下一步”。我第一次敲 node -v 看到版本号出现的时候，心情跟考过驾照差不多。

二、把博客在本地跑起来

1. 初始化

1
2
3
4
5

# 找个喜欢的位置，比如 D:\
cd D:\
hexo init blog
cd blog
npm install

hexo init 搭骨架，npm install 装依赖。两步都别慌，屏幕滚一堆字是正常的。

2. 装 anzhiyu 主题

1

npm install hexo-theme-anzhiyu

打开根目录的 _config.yml，找到 theme: 一行，改成：

1

theme: anzhiyu

3. 装配套插件（本站实际在用的清单）

1

npm install hexo-abbrlink hexo-generator-searchdb hexo-generator-feed hexo-generator-sitemap hexo-wordcount

各自负责：

• hexo-abbrlink：每篇文章一个永久短链接，换主机不失效
• hexo-generator-searchdb：站内搜索
• hexo-generator-feed：RSS 订阅
• hexo-generator-sitemap：站点地图，方便搜索引擎收录
• hexo-wordcount：字数统计

4. 本地预览

1

npx hexo server

浏览器打开 http://localhost:4000，看到你自己的博客了。

目录里最需要认识的两个地方：source/_posts/（以后文章全住这）和 _config.yml（全站配置）。

5. 新建一篇文章试试

1

npx hexo new post "我的第一篇文章"

Hexo 会在 source/_posts/ 生成同名 .md 文件。用任意编辑器（VSCode、Typora 都行）打开，front matter 下面随便写两句，保存，刷新浏览器就能看到。

踩坑旁白：我第一次打开 localhost:4000，对着页面发了三分钟呆，然后截图发了好几个群。冷静下来才想起：博客一篇文章都还没有——别急，先部署，文章慢慢写。

三、Git 仓库：给博客上”户口”

Cloudflare Pages 只认 GitHub 仓库，所以本地博客得先”上户口”。

1. 在 GitHub 建一个仓库

登录 GitHub → 右上角 + → New repository：

• 名字随意（我用的是 xxx.github.io 格式）
• 选 Private（私有）——踩坑过程不想被围观，就选私有
• 其他都不勾，Create

2. 先说一个大坑：仓库套仓库

我最初把 blog 放在另一个大仓库的子目录里，结果 CFP 构建永远失败——部署平台只认仓库根目录，它在仓库根找 package.json，当然找不到。

记住：blog 文件夹自己就是一个仓库。如果你已经套进去了，解法在第六节坑一。

3. 本地建仓库并推送

1
2
3
4
5
6
7

cd D:\blog
git init
git add .
git commit -m "init: 博客上线第一步"
git branch -M main
git remote add origin git@github.com:你的用户名/你的仓库名.git
git push -u origin main

逐行翻译：

• git init：把当前文件夹变成一个仓库
• git add . + git commit：给所有文件拍一张快照，附言”init”
• git branch -M main：分支命名为 main（GitHub 的习惯）
• git remote add：本地仓库和 GitHub 仓库”配对”
• git push：把快照推上去

推不动？连接超时？别怀疑人生，是国内网络在拦你，看下一条。

4. 国内网络解法：SSH 走 443

github.com 网页能打开，但 git 用的接口经常连不通。解法：让 git 改走 SSH 协议的 443 端口——同样是 443，换协议就稳了。

第一步：还没有 SSH 密钥就先生成（有就跳过）：

1
2

ssh-keygen -t ed25519 -C "你的邮箱"
# 一路回车

把 C:\Users\你的用户名\.ssh\id_ed25519.pub 里的内容复制，粘贴到 GitHub → Settings → SSH and GPG keys → New SSH key。

第二步：在 C:\Users\你的用户名\.ssh\ 下新建一个 config 文件（没有后缀名，VSCode 另存为时手动删掉 .txt），内容四行：

1
2
3
4

Host github.com
  HostName ssh.github.com
  Port 443
  User git

第三步：验证：

1

ssh -T git@github.com

看到 Hi 你的用户名! You've successfully authenticated 就通了。

踩坑旁白：看到那句 “successfully authenticated” 时我对屏幕说了句”就这？”——是的，就这。配一次，以后所有 push 都走这条稳定通道。

5. 最后一个文件：.nvmrc

在博客根目录新建 .nvmrc，内容只有一行：

1

20

这是给 Cloudflare Pages 看的：构建时用 Node 20，和你本地一致，避免”本地好好的、云端构建报错”。

注意：用编辑器新建保存。别用 PowerShell 的重定向生成——它会存出错误编码，云端读不到。

再推一次：

1
2
3

git add .
git commit -m "chore: SSH 通道与 nvmrc"
git push

四、Cloudflare Pages：把仓库接到云端

1. 创建项目

登录 Cloudflare 控制台 → 左侧 Workers & Pages → Create → Pages 标签 → Connect to Git。

2. 授权 GitHub

第一次会要你授权，点 Install & Authorize，勾选你的博客仓库。私有仓库也能连，授权一次以后都自动读。

3. 填配置（核心就三样）

Node 版本不用选——它自动读 .nvmrc（上一步建的那个）。

点 Save and Deploy，第一次构建开始。去 Deployments 页看实时日志，几分钟内状态变绿，送你一个 xxx.pages.dev 默认域名。

4. 打开看看

点开那个 pages.dev 域名。能打开——恭喜全链路打通；打不开——不是你配错了，是默认域名国内被墙，看第六节坑三（所以要绑自己的域名）。

踩坑旁白：第一次构建转圈的时候，我盯着日志页刷新了不下二十次。事后想起来明明有邮件通知……但那一刻就是忍不住。

五、日常发布：以后只要四步

部署是一次性的，之后发文章是日常。流程固化成四步：

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 新建文章
npx hexo new post "新文章标题"

# 2. 写作（用编辑器打开 source/_posts/ 里的新文件）

# 3. 本地验证
npx hexo generate

# 4. 推送上线
git add .
git commit -m "post: 新文章标题"
git push

push 之后一分钟内，Cloudflare Pages 自动构建、自动上线，读者刷新就能看到。

两个习惯：

• 本地验证是底线：hexo generate 报错就在本地解决。构建虽然自动，但每次都红着影响心情。
• 为什么不用 hexo deploy：Hexo 自带 hexo d，但要单独配服务器凭证。我们已经有”push 即部署”这条全自动链路，一条链路好过两条——我的 _config.yml 里 deploy 那段是直接注释掉的。

六、我替你踩过的四个坑

坑一：仓库套仓库 → CFP 找不到 package.json

症状：构建日志一直红，报找不到 package.json。
原因：博客套在别的仓库的子目录里，CFP 只认仓库根。
解法（我的实际操作）：用 git subtree split 把 blog 从大仓库里剥出来：

1
2
3
4
5

# 在大仓库的根目录执行
git subtree split -P blog -b blog-split

# 把剥出来的分支推到新仓库
git push git@github.com:你的用户名/博客仓库.git blog-split:main --force

然后到 CFP 项目设置里把仓库指到新仓库（或重建项目连新仓库），构建立刻就绿。
一句话预防：一开始就让 blog 文件夹独立成仓库，就没有这个坑。

坑二：api.github.com 连不通

症状：git 操作超时，挂了代理也不行。
解法：第三节配好的 SSH 443 通道就是为它准备的。配一次永久受益。

坑三：部署成功，pages.dev 打不开

症状：CFP 显示 Success，国内浏览器就是访问不了。
原因：默认域名 *.pages.dev 国内被墙。
解法：绑定自己的域名——CFP 项目 → Custom domains → 添加域名，按提示加 DNS 解析记录。这是国内能访问的前提，也是我上线 checklist 的硬性一项。

坑四：构建成功但站内链接不对

症状：网站能打开，点链接却跳到 localhost 或 404。
原因：_config.yml 的 url 还是默认值。
解法：

1

url: https://你的正式域名

改完 push 一次，顺手把导航菜单每项点验一遍。

七、上线前 Checklist

域名解析生效要几分钟到几小时，打不开先别慌——多半不是坏了。

写在最后

回到开头的人设：我是拾柒，不会写代码。这篇教程里的每条命令、每张图，都是我和 AI 协作完成的——AI 负责写命令、画图解，我负责踩坑、验证、拍板。

而它此刻正在被你读到，恰好就是这套流程的证明：我改完最后一版，hexo generate 一绿，git push 一下——一分钟内，它自己上线了。

祝你也能一次就绿。

参考

• Hexo 官方文档
• anzhiyu 主题
• Cloudflare Pages 文档
• GitHub 官方：通过 443 端口使用 SSH