Hexo博客多端部署说明

最近换了新电脑，想继续写博客的时候发现之前的Hexo博客只在旧电脑上有配置，换个设备就得重新折腾半天。相信很多用Hexo的朋友都遇到过类似问题——家里用台式机、出门带笔记本，想在哪都能写博客可太麻烦了。所以整理了这份多端部署指南，不仅包含完整的多端同步步骤，还严格按照我个人的Git使用规范来写，同时补充了环境配置细节（比如为什么不全局装Hexo、NPX到底好用在哪），以及最常见的「butterfly主题文件夹为空导致白屏」的修复方法，新手也能轻松看懂！

为什么需要多端部署？

咱们写博客的时候经常会遇到这些场景：

公司电脑写了一半的文章，回家想用笔记本接着写，却发现源码不在身边；
换了新设备，重新配置Hexo环境要装一堆依赖，还容易因为版本不一致报错；
担心电脑突然坏掉，博客源码没备份，之前写的文章全丢了；
同步后发现博客部署白屏，排查半天才知道是butterfly主题文件没同步。

多端部署就是为了解决这些问题，核心好处有3个：

随时随地编辑：任何设备只要拉取源码，就能继续写博客；
环境统一：避免不同设备的Hexo版本冲突，减少报错；
自动备份：源码存在云端仓库，不怕设备故障导致数据丢失。

多端部署的原理

简单说就是“云端存源码，本地读配置，统一用NPX跑命令，Git按规范同步”，流程特别好理解：

把Hexo的“源文件”（比如source/文章、themes/主题、_config.yml配置）存到GitHub/Gitee仓库；
每个设备（旧电脑、新电脑、笔记本）都按统一的Git规范拉取/推送源码；
不用在每个设备全局装Hexo，用NPX直接调用项目本地的Hexo版本，避免版本冲突；
写文章后推送到仓库同步，再部署到GitHub Pages等平台；
同步后检查主题文件夹完整性，避免白屏问题。

准备工作

需要提前准备这些东西，少一个都不行哦：

已经搭建好的Hexo博客（任意一台设备，作为“源码基准”）；
GitHub/Gitee账号（用来存源码仓库和部署静态博客页面）；
所有需要同步的设备（电脑）都安装好：Git + Node.js（LTS版本，16+就行）。

具体操作步骤（分3部分：环境配置+Git同步+主题白屏修复）

第一部分：基础环境配置（所有设备都要做）

这一步是核心！重点说清“为什么不全局装Hexo”，以及“NPX怎么用”。

1. 安装基础依赖（Git + Node.js）

Windows/macOS：直接从Node.js官网下载LTS版本，安装时勾选“Add to PATH”；Git从Git官网下载安装，安装时选“Git Bash Here”。

Ubuntu/Linux：

sudo apt update && sudo apt install nodejs npm git -y

验证是否安装成功：打开终端输入以下命令，能显示版本号就没问题：

node -v  # 显示v16.x或更高
npm -v   # 显示6.x或更高
git -v   # 显示2.x或更高

2. 为什么不全局安装 Hexo？用 NPX 的原因是什么？

很多教程会让你用npm install -g hexo-cli全局安装，但多端部署场景下强烈不推荐！原因有 3 个：

版本冲突：全局安装的 Hexo 是固定版本，比如你旧电脑装的是 Hexo 6.x，新电脑装的是 7.x，同步源码后可能因为版本不兼容报错（比如某些命令失效、主题不兼容）；
环境污染：全局安装需要系统权限（Linux/macOS 要加sudo），可能误修改系统文件，卸载也容易残留；
多项目干扰：如果以后要维护多个 Hexo 博客，全局版本只能选一个，必然导致其中一个项目出问题。

那为什么用 NPX？

NPX 是 Node.js 自带的工具，能直接调用项目本地的 Hexo 版本（存放在node_modules/里），不用全局安装；
只要项目的package.json记录了 Hexo 依赖，任何设备npm install后，用npx hexo xxx就能直接运行，保证所有设备用的是同一个 Hexo 版本；
不用手动管版本，新设备拉取源码后，安装依赖就自动同步，零配置成本。

3. 项目本地安装 Hexo（关键！替代全局安装）

在你的 Hexo 博客根目录（比如hexo-blog）执行以下命令，把 Hexo 安装到项目本地：

# 进入Hexo根目录（替换为你的实际路径）
cd ~/Personal/Blog-source

# 本地安装hexo-cli（写入package.json，方便多端同步）
npm install hexo-cli --save-dev

# 安装Hexo核心依赖和主题依赖（比如Butterfly需要的解析器）
npm install hexo-renderer-pug hexo-renderer-stylus --save

安装完成后，项目目录里会多出node_modules/文件夹（存放本地依赖）和package.json文件（记录依赖版本），这两个文件后续会通过 Git 规范同步到云端，让所有设备保持一致。

4. 配置 npm 脚本（可选，更方便调用命令）

编辑 Hexo 根目录的package.json，添加scripts字段，以后用npm run xxx就能执行 Hexo 命令，比输npx hexo xxx更短：

{
  "name": "hexo-blog",
  "version": "1.0.0",
  "scripts": {
    "clean": "hexo clean",
    "dev": "hexo server",
    "build": "hexo generate",
    "deploy": "hexo deploy",
    "publish": "hexo clean && hexo d -g"
  },
  "devDependencies": {
    "hexo-cli": "^4.3.0"
  }
}

第二部分：多端同步部署操作（严格按我的 Git 规范来）

1. 初始化源码仓库（仅在“基准设备”操作，比如旧电脑）

先在 GitHub 新建一个仓库（比如叫hexo-source），用来存 Hexo 源码，然后严格按以下 Git 命令执行：

# 进入Hexo根目录
cd ~/Personal/Blog-source

# 初始化Git仓库
git init

# 主分支命名（强制改为main，个人开发统一规范）
git branch -M main

# 添加远程仓库地址（替换为你的仓库地址，HTTPS或SSH都可以）
git remote add origin https://github.com/你的用户名/hexo-source.git

# 创建.gitignore文件（关键！避免上传无用文件，注意不要忽略themes/）
cat > .gitignore << EOF
# 依赖目录
node_modules/
# 构建输出目录
public/
.deploy_git/
# 缓存文件
db.json
*.log
# 系统文件
.DS_Store
Thumbs.db
# 编辑器配置
.vscode/
.idea/
EOF

# 首次提交（备注清晰，个人开发规范）
git add .
git commit -m "Initial commit: 初始化Hexo源码，包含本地依赖配置"

# 关联远程并推送（-u记录upstream，后续可直接git push/pull）
git push -u origin main

⚠️ 重点提醒：.gitignore里绝对不要加themes/或themes/butterfly/，否则会导致主题文件无法同步，部署后白屏！

2. 新设备同步配置（严格按我的 Git 使用流程）

在其他设备上，按以下规范操作，3 步就能同步所有配置，直接写博客：

第一步：拉取最新源码（每次开始工作前必做）

# 克隆云端源码仓库到本地（替换为你的仓库地址）
git clone https://github.com/你的用户名/hexo-source.git

# 进入项目目录
cd hexo-source

# 个人开发最稳的拉取方式：保持历史线性，避免冲突
git pull --ff-only

第二步：安装依赖（自动同步版本）

npm install

第三步：日常操作规范（完全参考我的 Git 使用流程）

本地预览：npx hexo s 或 npm run dev（配置了脚本的话）
写文章：npx hexo new "文章标题"

开发过程中同步：

git status
git add .
git commit -m "新增文章：Hexo多端部署指南"

结束工作推送：

git push

新增功能 / 修改主题（比如改 butterfly 配置）：

git switch -c feature_butterfly_config
git add .
git commit -m "修改butterfly主题：新增侧边栏配置"
git switch main
git merge feature_butterfly_config
git push

⚠️ 个人开发绝对不要用git rebase！会重写提交历史，多设备同步必出问题，用merge虽然“丑”但安全、可回滚。

3. 冲突处理（严格按我的规范）

如果两个设备同时改了同一个文件（比如都编辑了_config.yml或themes/butterfly/_config.yml），会出现冲突，解决步骤：

git status
# 手动编辑冲突文件（Git会标注冲突位置），保留需要的内容
git add <冲突文件名>
git commit -m "解决冲突：合并butterfly主题配置"
git push

Git 不会自动解决冲突，必须手动修改，这是个人开发最安全的方式。

第三部分：特殊问题修复 —— themes/butterfly 文件夹为空导致部署白屏

这是多端同步最常见的问题，同步后部署白屏，90% 是因为themes/butterfly文件夹为空或文件不完整！

1. 问题现象

本地执行npx hexo g时出现大量WARN No layout: xxx.html；
本地预览npx hexo s白屏，或部署到 GitHub Pages 后白屏；
执行ls themes/butterfly显示空（无layout/、source/等文件夹）。

2. 核心原因

Git 同步时themes/butterfly未被追踪（比如误加进.gitignore）；
主题文件夹是 Git 子模块，但未初始化；
克隆仓库时未拉取完整的主题文件。

3. 解决步骤

步骤 1：检查主题文件夹状态

cd ~/Personal/Blog-source
ls -la themes/butterfly
git status themes/butterfly

步骤 2：修复空文件夹（分两种情况）

情况 1：主题不是 Git 子模块（手动安装的）

rm -rf themes/butterfly
git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

git add themes/butterfly
git commit -m "修复：重新拉取butterfly主题文件，解决白屏问题"
git push

情况 2：主题是 Git 子模块（旧电脑上用 submodule 管理）

git submodule init
git submodule update --init --recursive

git add .
git commit -m "修复：初始化butterfly子模块，解决白屏问题"
git push

步骤 3：验证修复效果

npx hexo clean
npx hexo g && npx hexo s

浏览器访问http://localhost:4000，能正常显示博客内容说明修复成功，再执行npx hexo d部署即可。

4. 预防措施（避免下次再出问题）

ls themes/butterfly
cat .gitignore | grep "themes" # 无输出才正常
git pull --ff-only
git submodule update --init --recursive

常见问题解决（整合版）

问题现象	解决方法
新设备npm install报错“依赖缺失”	删除node_modules和package-lock.json，重新执行npm install
用npx hexo s提示“command not found”	确认node_modules/.bin/目录下有hexo文件，或重新执行npm install hexo-cli --save-dev
部署时报 Git 认证失败	1) 配置 Git 用户名邮箱；2) 改用 SSH 地址克隆仓库
themes/butterfly 为空导致白屏	按第三部分步骤重新拉取主题文件，确保.gitignore 不忽略 themes/
Git 拉取 / 推送冲突	按“冲突处理”步骤手动解决，不要用 rebase

总结

多端部署的核心逻辑就是：用我规范的 Git 流程同步源码，用 package.json 锁定依赖版本，用 NPX 调用本地 Hexo，同步后检查主题文件夹完整性，不用在每个设备反复配置环境，一次设置终身受益。

关键要点回顾：

不全局装 Hexo，避免版本冲突，用本地安装 + NPX 调用；
Git 操作严格按规范：主分支 main、每次拉取用 pull --ff-only、新增功能建分支、不用 rebase、冲突手动解决；
绝对不要忽略 themes 文件夹，同步后检查 butterfly 完整性，避免白屏；
操作前先拉取、操作后先推送，多设备同步不翻车。

这样一来，不管你在办公室、家里还是外出，只要有网络，打开电脑就能按统一规范写博客，再也不用担心灵感来了却没法记录，也不用怕换设备后部署白屏啦！