Hexo博客部署常见问题及解决方案

在使用 Hexo 部署博客的过程中，常会遇到各种报错。本文整理了从 Node.js 版本兼容到 SSH 密钥配置的全套解决方案，帮助你快速排查并解决问题。

一、环境准备与依赖修复

1. 清除缓存与修复依赖

若部署时出现未知错误（如文件复制失败、模块缺失），优先修复依赖：

1
2
3
4
5
6
7
8
# 清除 Hexo 缓存
hexo clean

# 删除损坏的依赖文件和锁文件
rm -rf node_modules package-lock.json yarn.lock

# 重新安装依赖
npm install

2. 安装 Node 版本管理工具（nvm）

Hexo 对 Node.js 版本有严格要求（推荐 v14.0.0+，旧主题建议 v16 LTS），使用 nvm 可灵活切换版本。

国内镜像安装（解决 GitHub 访问受限）：

1
2
# 用 Gitee 镜像安装 nvm（速度更快）
curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.3/install.sh | bash

加载 nvm 配置（立即生效）：

安装后关闭终端重开，或手动加载配置：

1
2
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # 加载 nvm 核心脚本

安装并切换 Node.js 版本：

1
2
3
4
5
6
7
8
# 安装 Node.js 16（兼容性较好）
nvm install 16

# 切换到已安装的版本
nvm use 16

# 验证版本
node -v  # 输出应为 v16.x.x

二、GitHub 主机密钥验证失败

报错特征：

部署时提示 Host key verification failed，因 GitHub 主机密钥更新，本地存储的旧密钥不匹配。

解决方案：

1
2
3
4
5
# 1. 删除本地存储的旧 GitHub 主机密钥
ssh-keygen -R github.com

# 2. 重新连接 GitHub 并信任新密钥
ssh -T git@github.com

执行后会提示确认新密钥，输入 yes 并回车，新密钥将自动保存到本地。

三、Node.js 版本兼容问题

报错特征

部署时出现类似 TypeError [ERR_INVALID_ARG_TYPE]: The "mode" argument must be of type number 的错误，通常是 Node.js 版本与 Hexo 或依赖不兼容导致。

解决方案

  1. 安装 nvm 管理 Node 版本

若无法访问 GitHub 资源，可使用国内镜像：

1
2
# 国内镜像安装 nvm
curl -o- https://gitee.com/mirrors/nvm/raw/v0.39.3/install.sh | bash

**加载 nvm 配置（立即生效）

1
2
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

安装并切换到兼容版本（推荐 Node.js 16）

1
2
3
4
nvm install 16
nvm use 16
# 验证版本
node -v  # 应显示 v16.x.x

四、GitHub 主机密钥验证失败

报错特征

部署时提示 Host key verification failed，因 GitHub 主机密钥更新导致本地校验不通过。

解决方案

删除旧主机密钥

1
ssh-keygen -R github.com

重新信任 GitHub 主机

1
ssh -T git@github.com

出现提示时输入 yes 确认，新密钥会自动保存。

五、SSH 权限问题（Permission denied）

报错特征

执行 ssh -T git@github.com 时提示 Permission denied (publickey)，说明 SSH 密钥未被 GitHub 识别。

解决方案

  1. 删除旧密钥（若存在）
1
2
rm -f ~/.ssh/id_rsa ~/.ssh/id_rsa.pub  # 删除 RSA 密钥
# 若有其他密钥（如 id_ed25519），也一并删除

生成兼容旧系统的 RSA 密钥

1
2
3
# 生成 4096 位 RSA 密钥（替换为你的邮箱）
ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"
# 按回车使用默认路径，无需设置密码（直接回车两次）

加载私钥并添加到 SSH 代理

1
2
3
4
# 启动代理
eval "$(ssh-agent -s)"
# 加载新生成的私钥
ssh-add ~/.ssh/id_rsa

将公钥添加到 GitHub

  • 复制公钥内容：

  • # macOS 自动复制
pbcopy < ~/.ssh/id_rsa.pub
# 其他系统：手动复制 cat ~/.ssh/id_rsa.pub 的输出

    1
    2
    3
    4
    5
    6
    7
    8

    - 登录 GitHub → **Settings** → **SSH and GPG keys** → **New SSH key** → 粘贴公钥并保存。

    **验证连接

    1. ```bash
       ssh -T git@github.com
       # 成功提示：Hi 你的用户名! You've successfully authenticated...

六、最终部署验证

完成上述配置后，重新部署 Hexo 博客：

1
hexo clean && hexo deploy

若仍有问题，可临时改用 HTTPS 部署（修改 _config.yml 中 deploy.repo 为 HTTPS 地址，如 https://github.com/用户名/仓库名.git），部署时输入 GitHub 账号密码或个人访问令牌。

通过以上步骤，可解决 Hexo 部署中常见的 Node 版本兼容、主机密钥验证及 SSH 权限问题，确保博客顺利部署到 GitHub。