从零搭建 Hexo+Cloudflare Pages 个人云博客

从零用VSCode + WSL2 + Hexo + GitHub + Cloudflare Pages 搭建个人云笔记博客

一、完整步骤

第一步：开启 WSL2

为什么要用 WSL2？
因为 Windows 自带的 PowerShell 命令和 Linux 不兼容，装 Hexo 会非常痛苦。WSL2 是微软官方的 Linux 子系统，性能几乎和原生 Linux 一样。

操作步骤：

1. 按 Win + X → Windows 终端（管理员）
2. 复制粘贴这行（一路回车）：

   wsl --install -d Ubuntu
   重启电脑（必须！）
   重启后会弹出一个黑色窗口，让你设置 Ubuntu 的用户名和密码
   → 用户名随便（建议小写英文，如 tom）
   → 密码随便（记好就行）
   完成 → 你现在拥有了一个真正的 Ubuntu 系统
   第二步：安装 VS Code + Remote - WSL（让 VS Code 直接运行在 Linux 里）
   为什么要装这个？
   这样你打开 VS Code，所有文件、终端都在 Linux 里，速度飞起，命令 100% 兼容。
   操作步骤：
   下载 VS Code：https://code.visualstudio.com/
   安装后打开
   左侧扩展（Ctrl+Shift+X）→ 搜索 “Remote - WSL” → 安装
   左下角出现绿色 >< → 点它 → Connect to WSL → 自动连接
   以后每次打开 VS Code 都自动在 WSL 里（左下角显示 [WSL: Ubuntu]）
   第三步：安装 Node.js 和 Hexo（解决权限大坑）
   为什么要自己改 npm 路径？
   系统自带的 Node.js 把全局安装目录设在 /usr/lib，普通用户没权限，npm install -g 会报 EACCES 错误。
   操作步骤：
   Bash# 安装 Node.js（官方推荐方式）
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt install -y nodejs
   

创建你自己的 npm 全局目录（解决权限问题）

mkdir -p /.npm-global/bin
npm config set prefix ‘/.npm-global’
echo ‘export PATH=~/.npm-global/bin:$PATH’ >> ~/.zshrc
source ~/.zshrc

安装 Hexo

npm install -g hexo-cli
第四步：创建 Hexo 项目（防套娃关键）
为什么 hexo init 会套娃？
因为它默认在当前目录再创建一个同名文件夹，导致你 cd 进去找不到文件。
正确操作：
Bashcd ~
mkdir MyBlog && cd MyBlog
hexo init . # 必须加点！表示在当前目录初始化
npm install
npm install hexo-generator-sitemap –save
第五步：安装 Fluid 主题（2025 最美主题，防 Cloudflare 构建失败）
为什么不能用 git clone？
因为 clone 下来的主题里有 .git 文件夹，Cloudflare Pages 会把它当子模块处理，构建时尝试 clone 失败。
正确操作（手动复制）：
Bash# 安装 unzip（如果没有）
sudo apt install -y unzip

下载并手动解压

wget -O fluid.zip https://github.com/fluid-dev/hexo-theme-fluid/archive/master.zip
unzip -q fluid.zip
mv hexo-theme-fluid-master themes/fluid
rm fluid.zip

启用主题

sed -i ‘s/theme: .*/theme: fluid/‘ _config.yml
第六步：本地预览（确认一切正常）
Bashhexo clean && hexo server
浏览器打开 http://localhost:4000
→ 看到漂亮的 Fluid 主题 + Hello World 文章 → 成功！
→ Ctrl+C 停止
第七步：推到 GitHub 私有仓库（推荐 SSH 方式）
为什么 SSH 比 HTTPS 好？
HTTPS 需要每次输入 Token，SSH 一次配置永远有效。
操作步骤：
Bash# 生成 SSH key
ssh-keygen -t ed25519 -C “你的邮箱” # 一路回车

复制公钥

cat ~/.ssh/id_ed25519.pub # 全选复制这行

去 GitHub → Settings → SSH and GPG keys → New SSH key → 粘贴 → Add

推代码（自动创建私有仓库）

git init
git branch -M main
git add .
git commit -m “init”
git remote add origin git@github.com:你的用户名/MyBlog.git
git push -u origin main
第八步：Cloudflare Pages 部署（终极配置）
打开 https://dash.cloudflare.com → Pages → Create a project → Connect to Git
选你的 GitHub 仓库
配置（直接复制）：
Project name：myblog（随便）
Production branch：main
Build command：npm install && npx hexo generate
Build output directory：public（必须填这个！）
Deploy command：echo “ok”（绕过必填）
Save and Deploy → 1～3 分钟后得到地址
第九步：彻底私有化（只有你能访问）
左侧 Zero Trust → Access → Applications → Add an application
Type：Self-hosted
Domain：填你的 pages.dev 地址
Policy → Allow → Emails → 填你的邮箱 → 勾 Require One-time PIN
Save
第十步：以后写文章（永远 3 步）
Bashhexo new “今天学到了什么”

VS Code 自动打开文件 → 写完保存

git add . && git commit -m “新笔记” && git push
二、真实踩过的所有坑 + 详细解决方案

坑错误提示为什么会发生解决方案hexo init 套娃cd MyBlog 找不到hexo init 默认再创建一层必须 hexo init .（加点）npm 权限错误EACCES: permission denied系统 Node.js 全局目录在 /usr/lib创建 ~/.npm-global 并改 PATHFluid 构建失败updating repository submodulesgit clone 主题有 .git 文件夹手动 wget + unzip 复制GitHub 推不上Repository not found用错地址或没加 SSH key用 SSH + 新生成的最新 key站点白屏Nothing is retrievedBuild output directory 填错必须填 public（不是 /）Deploy command 报错RequiredCloudflare 强制要求填填 echo “ok” 绕过HTTPS 警告非专用连接SSL 没开 Full (strict)Settings → SSL/TLS → Full (strict)
三、最终成果
本地路径：/home/tom/MyBlog
源码仓库：GitHub Private
站点地址：https://myblog-xxxx.pages.dev
访问方式：邮箱 + 6 位验证码
更新速度：30 秒全球同步
四、更新已发布的文章内容
Bash# 在 ~/MyBlog 目录下直接运行这一行（推荐）
git add . && git commit -m “更新：文章内容” && git push
或者更安全（防止误提交）：
Bashgit add source/_posts/你要改的那篇.md
git commit -m “更新：具体改了啥”
git push
五、新写一篇博客并推送到 GitHub，Cloudflare 自动构建
Bash# 一行命令全自动版
hexo new “文章标题” && code source/_posts/文章标题.md && git add . && git commit -m “新文章：文章标题” && git push
或者分步版（更清晰，适合新手）：
Bash# 1. 新建文章
hexo new “2025-11-24 今天学到的三个技巧”

2. 编辑（自动用 VS Code 打开）

code source/_posts/2025-11-24-今天学到的三个技巧.md

3. 写完保存后，回到终端执行推送（触发 Cloudflare 构建）

git add . && git commit -m “新文章：今天学到的三个技巧” && git push
终极懒人一键函数（只配置一次，之后每天只敲一行）
把下面这行加到你的 ~/.zshrc（只做一次）：
Bashecho ‘note() { hexo new “$1” && code “source/_posts/$1.md” && git add . && git commit -m “新文章：$1” && git push; }’ >> ~/.zshrc && source ~/.zshrc
以后每天写新文章就只敲这一行（标题自己改）：
Bashnote “2025-11-24 深度学习笔记”
→ 自动新建 + 打开编辑 + 提交 + 推送 + 1 分钟后全球同步
懒到极致，效率拉满。
—20251124
一、正确流程

1. 开启WSL2 + VSCode Remote_WSL
   环境介绍：VSCode Remote_WSL + Ubuntu Linux盘部署
   VS Code 必装扩展：
   Remote - WSL（Microsoft 官方）
   安装完左下角点绿色 >< → Connect to WSL → 以后自动进 [WSL: Ubuntu]
   每次打开 VS Code 自动进 WSL 的终极方法：
   PowerShell# Win + R → 输入这行 → 回车（或者做桌面快捷方式）
   code –folder-uri vscode-remote://wsl+Ubuntu/home/用户名/MyBlog
2. 项目环境安装 Node.js + 彻底解决 npm 权限
   Bash# 安装 Node.js（最干净方式）
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt install -y nodejs

解决 npm 全局安装权限问题

mkdir -p /.npm-global/bin
npm config set prefix ‘/.npm-global’
echo ‘export PATH=~/.npm-global/bin:$PATH’ >> ~/.zshrc
source ~/.zshrc

全局安装 hexo-cli

npm install -g hexo-cli

创建 Hexo 项目（防套娃关键）

Bashcd ~
mkdir MyBlog && cd MyBlog
hexo init . # 一定要加点！
npm install
npm install hexo-generator-sitemap –save
npm install hexo-deployer-git –save

安装 Fluid 主题（避免子模块坑）

Bash# 手动复制方式（Cloudflare 100% 通过）
sudo apt install -y unzip
wget -O fluid.zip https://github.com/fluid-dev/hexo-theme-fluid/archive/master.zip
unzip -q fluid.zip
mv hexo-theme-fluid-master themes/fluid
rm fluid.zip

创建 override 配置（官方推荐）

cp themes/fluid/_config.yml _config.fluid.yml
sed -i ‘s/theme: .*/theme: fluid/‘ _config.yml

本地测试

Bashhexo clean && hexo server

浏览器打开 http://localhost:4000 → Ctrl+C 停止

GitHub 私有仓库 + SSH 推送

Bashgit init
git branch -M main
git add .
git commit -m “init: hexo + fluid”
git remote add origin git@github.com:用户名/仓库名.git
git push -u origin main

(二) GitHub 私有仓库（SSH 终极解）

Bashssh-keygen -t ed25519 -C “你的邮箱” # 一路回车
cat ~/.ssh/id_ed25519.pub # 复制这行

去 GitHub → Settings → SSH keys → New SSH key → 粘贴

git init && git branch -M main
git add .
git commit -m “init”
git remote add origin git@github.com:你的用户名/MyBlog.git
git push -u origin main

Cloudflare Pages 终极配置

Project name：随便填（如 myblog）
Production branch：main
Build command：npm install && npx hexo generate
Build output directory：public（必须填这个！）
Deploy command：echo “deploy ok”（绕过必填）
Save and Deploy

完全私有化（Zero Trust，免费）

Zero Trust → Access → Applications → Add an application
Type：Self-hosted
Domain：你的 pages.dev 地址
Policy → Allow → Emails（填你的邮箱）→ 勾 Require One-time PIN
Save → 访问需要邮箱 + 6 位验证码

以后写文章永远 3 步

Bashhexo new “标题”

VS Code 编辑 source/_posts/xxx.md

git add . && git commit -m “新笔记” && git push
二、踩过的所有坑 + 终极解决方案

序号坑错误表现终极解决方案1hexo init 套娃cd MyBlog 找不到必须 hexo init .（加点）2npm 权限问题EACCES /usr/lib创建 ~/.npm-global 并改 PATH3Fluid 子模块构建失败Cloudflare 报 updating submodules手动 wget + unzip 复制主题文件4GitHub 推不上Repository not found用 SSH + 新生成的最新 key5Build output directory 填错站点白屏必须填 public（不是 /）6Deploy command 必填报错Required填 echo “ok” 绕过7HTTPS 警告非专用连接SSL/TLS → Full (strict) + Purge cache8站点显示 Nothing is retrieved空页Purge cache + 强制刷新 + 等 CDN 传