Hexo 个人博客从搭建到上线全流程（含踩坑指南）

Hexo 个人博客从搭建到上线全流程（含踩坑指南）

一、环境准备（必做）

1. 安装 Node.js

• 作用：Hexo 运行的底层环境
• 下载地址：Node.js 官网（选 LTS 长期支持版，如 v20.x）
• 验证：终端执行 node -v 和 npm -v，显示版本号则成功。

2. 安装 Git

• 作用：版本控制 + 部署到 GitHub 必备
• 下载地址：Git 官网（Windows 需勾选「Add Git to PATH」）
• 验证：终端执行 git --version，显示版本号则成功。

二、安装并初始化 Hexo

1. 全局安装 Hexo CLI

终端执行：

npm install -g hexo-cli

验证：hexo -v 显示版本号则成功。

2. 初始化博客项目

mkdir my-hexo-blog  # 新建博客文件夹
cd my-hexo-blog     # 进入文件夹
hexo init           # 初始化 Hexo
npm install         # 安装依赖

三、本地预览与第一篇文章

1. 启动本地服务器

hexo clean && hexo g && hexo s

• 访问 http://localhost:4000 即可预览。

2. 发布第一篇文章

hexo new "我的第一篇 Hexo 博客"

• 打开 source/_posts/我的第一篇 Hexo 博客.md，用 Markdown 写内容后，重新执行 hexo clean && hexo g && hexo s 即可看到文章。

四、更换主题（以 Butterfly 为例）

1. 下载主题

git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

2. 安装主题依赖

npm install hexo-renderer-pug hexo-renderer-stylus --save

3. 配置主题

• 复制 themes/butterfly/_config.yml 到根目录，并重命名为 _config.butterfly.yml。
• 修改根目录 _config.yml，设置 theme: butterfly。

五、部署到 GitHub Pages（免费上线）

1. 准备 GitHub 仓库

• 新建仓库，名称必须为 你的用户名.github.io（如 xxx.github.io）。

2. 安装部署插件

npm install hexo-deployer-git --save

3. 配置部署信息（修改根目录 _config.yml）

deploy:type: gitrepo: https://github.com/你的用户名/你的用户名.github.io.gitbranch: main

4. 执行部署

hexo clean && hexo g && hexo d

• 访问 https://你的用户名.github.io 即可看到线上博客。

六、踩坑指南（避坑必备）

1. 「没有权限修改 _config.yml 文件」

• 原因：文件权限不足或被占用。
• 解决：
  • Windows：右键编辑器 →「以管理员身份运行」，或修改文件夹权限（属性→安全→完全控制）。
  • Mac/Linux：终端执行 sudo chown -R $USER 博客文件夹 赋予权限。

2. 部署时「Spawn failed」错误

• 原因：Git 环境变量未配置、部署配置错误、网络问题等。
• 解决：
  • 检查 Git 环境变量（终端执行 git --version 验证）。
  • 核对 _config.yml 中 deploy 的 repo 和 branch 是否正确。
  • 国内网络可尝试挂梯子，或修改 Git 镜像：git config --global url."https://github.com.cnpmjs.org/".insteadOf "https://github.com/"。

3. GitHub 密码验证失败

• 原因：GitHub 已停用 HTTPS 密码验证，需用个人访问令牌或 SSH。
• 解决：
  • 生成 GitHub 个人访问令牌，部署时密码填令牌。
  • 配置 SSH 免密：生成 SSH 密钥 → 配置到 GitHub → 修改 deploy 的 repo 为 SSH 地址（[e-mail]:xxx/xxx.github.io.git）。

4. SSH 连接「Connection refused」

• 原因：端口 22 被屏蔽。
• 解决：修改 SSH 配置走 443 端口，在 ~/.ssh/config 中添加：

  Host github.comHostname ssh.github.comPort 443
  

5. YAML 配置「duplicated mapping key」错误

• 原因：配置文件中出现重复键名（如 waline: 重复）。
• 解决：打开 _config.butterfly.yml，删除重复的键块，确保同一层级键名唯一。

七、优化与扩展

• 自定义域名：在 GitHub Pages 配置中绑定域名，并在 source/ 下新建 CNAME 文件填写域名。
• 评论功能：推荐用 Waline，需先部署服务端获取 serverURL，再在主题配置中启用。
• SEO 优化：安装 hexo-generator-sitemap 等插件，配置站点关键词和描述。

按照以上步骤，即可从 0 到 1 搭建并个性化你的 Hexo 博客，遇到问题可参考「踩坑指南」快速解决～