Hexo + GitHub + Vercel 多电脑使用指南

这套流程适用于在工作电脑、家用电脑之间切换使用 Hexo，并让 Vercel 自动发布网站。

一、整体流程

1
2
3
4
5
6
7
8
9
10
11
12
本地电脑修改 Hexo 源码
        |
        | git push
        v
GitHub 保存源码
        |
        | 自动触发部署
        v
Vercel 执行 npm ci + hexo generate
        |
        v
线上网站更新

以后不需要执行 hexo deploy，Vercel 会负责发布。

二、项目中应该提交什么

应提交到 GitHub 的内容：

1
2
3
4
5
6
7
8
9
source/
scaffolds/
themes/                  # 仅当主题是普通目录或子模块时
_config.yml
_config.主题名.yml       # 如果主题支持独立配置
package.json
package-lock.json
.gitignore
.gitmodules               # 使用 Git 子模块时才有

不应提交：

1
2
3
4
5
node_modules/
public/
.deploy_git/
db.json
.vercel/

.gitignore 至少应包含：

1
2
3
4
5
6
7
node_modules/
public/
.deploy_git/
db.json
.vercel/
.DS_Store
Thumbs.db

三、首次上传到 GitHub

在 Hexo 项目根目录执行。远程地址必须是纯 URL，不要包含 Markdown 的 [] 或 ()：

1
2
3
4
5
6
git init
git add .
git commit -m "Initial Hexo blog"
git branch -M main
git remote add origin https://github.com/你的用户名/你的仓库.git
git push -u origin main

如果提示 remote origin already exists，不要再次添加，先修正地址：

1
2
git remote set-url origin https://github.com/你的用户名/你的仓库.git
git remote -v

正确输出应类似：

1
2
origin  https://github.com/你的用户名/你的仓库.git (fetch)
origin  https://github.com/你的用户名/你的仓库.git (push)

如果出现 src refspec main does not match any，通常是当前分支不是 main 或还没有提交。按以下顺序处理：

1
2
3
4
git add .
git commit -m "Initial Hexo blog"
git branch -M main
git push -u origin main

如果出现 Failed to connect to github.com:443，这是网络、代理或公司防火墙问题。可以检查：

1
2
3
curl -I https://github.com
git config --global --get http.proxy
git config --global --get https.proxy

确认不需要代理时可以清除错误代理：

1
2
3
git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global http.version HTTP/1.1

也可以切换手机热点后重试 git push。

四、Vercel 配置

在 Vercel 中选择 Add New -> Project，导入 GitHub 仓库。

如果仓库根目录就是 Hexo 项目，配置如下：

1
2
3
4
5
Framework Preset: Hexo
Root Directory: ./
Build Command: npm run build
Output Directory: public
Install Command: npm ci

如果项目的 package.json 位于仓库的 blog 子目录，才把 Root Directory 改为 blog。

环境变量通常不需要填写。删除空的示例变量，例如 EXAMPLE_NAME。

package.json 建议包含：

1
2
3
4
5
6
7
{
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "server": "hexo server"
  }
}

如果没有 build 脚本，可以在项目根目录执行：

1
2
3
4
npm pkg set scripts.build="hexo generate"
git add package.json package-lock.json
git commit -m "Add Vercel build script"
git push

五、新电脑首次使用

安装 Git 和 Node.js。Node.js 建议与其他电脑及 Vercel 使用相同的主版本，例如 Node.js 20 或 22。

在新电脑执行：

1
2
3
4
5
mkdir -p ~/Documents/Hexo
cd ~/Documents/Hexo
git clone https://github.com/你的用户名/你的仓库.git blog
cd blog
npm ci

如果仓库使用了 Git 子模块，应使用：

1
git clone --recurse-submodules https://github.com/你的用户名/你的仓库.git blog

已经克隆过但主题目录为空时：

1
git submodule update --init --recursive

启动本地预览：

1
2
npx hexo clean
npx hexo server

浏览器打开：http://localhost:4000

六、日常工作流程

开始工作前，先同步远程版本：

1
2
cd ~/Documents/Hexo/blog
git pull --rebase

如果 package.json 或 package-lock.json 有变化，再执行：

1
npm ci

修改文章或配置后，本地检查：

1
2
npx hexo clean
npx hexo server

确认没有问题后提交：

1
2
3
4
git status
git add .
git commit -m "说明本次修改"
git push

推送后，Vercel 会自动创建新的部署。部署状态显示 Ready 后，线上网站就是最新版本。

七、主题和 node_modules

如果主题是通过 npm 安装到 node_modules：

  • 不要把 node_modules 提交到 GitHub。
  • 必须提交 package.json 和 package-lock.json。
  • 新电脑和 Vercel 会通过 npm ci 自动重新安装主题。
  • 不要直接修改 node_modules 中的主题文件，因为这些修改会在 npm ci、换电脑或 Vercel 部署时消失。

主题更新应使用：

1
2
3
4
5
6
7
npm install hexo-theme-主题名@latest --save
npx hexo clean
npx hexo generate
npx hexo server
git add package.json package-lock.json
git commit -m "Update theme"
git push

如果只是增加自定义 JS，优先把文件放在：

1
source/js/custom.js

再按照主题文档提供的 inject、custom_js 或页脚配置加载。

如果必须修改 npm 主题内部源码，可以使用 patch-package 保存差异；长期大量修改则建议 Fork 主题仓库。不要只在 node_modules 中手动改完就结束。

八、图片、密钥和冲突

文章图片可以放在：

1
source/images/

不要把图片或文件放在 public/，因为 hexo clean 会删除该目录。

不要把密码、API Token 或私钥提交到 GitHub。线上密钥放到 Vercel 的 Environment Variables；本地需要时在本机单独配置，并确保相关文件被 .gitignore 忽略。

不要在两台电脑上同时修改同一篇文章或同一份配置。切换电脑时遵循：

1
2
开始：git pull --rebase
完成：git add -> git commit -> git push

如果 git pull 产生冲突，先解决冲突、测试本地生成，再提交并推送；不要在未解决冲突时强行推送。

九、常用排查命令

1
2
3
4
5
6
7
git status
git remote -v
git branch --show-current
git log --oneline -5
npm ls --depth=0
npx hexo clean
npx hexo generate

最简记忆：

1
2
3
4
新电脑：git clone -> npm ci
开始工作：git pull --rebase
完成工作：git add -> git commit -> git push
线上发布：Vercel 自动完成