GitHub + Hexo 搭建免费个人博客

发表于2016-06-10|更新于2026-07-21|随笔

本文写于 2016 年，示例环境以 Hexo 3.2.2 为主。Hexo 和 GitHub Pages 的配置方式会随版本变化，实际操作时建议优先参考当前版本文档；本文更适合作为基础流程和排查思路参考。

正文

这篇教程主要面向 macOS。写博客一方面是给自己做笔记，另一方面也能训练表达和总结能力。相比直接使用第三方博客平台，Hexo 更适合想掌控主题、域名和部署流程的个人博客。

配置环境

安装Node.js（必须）

作用：用来生成静态页面。
到 Node.js 官网下载相应平台的稳定版本，按照提示安装即可。

安装Git（必须）

作用：把本地的 Hexo 内容提交到 GitHub。
如果已经安装了 Xcode，系统通常会自带 Git。

申请GitHub（必须）

作用：用于托管博客的远程仓库和 GitHub Pages 站点。
如果还没有 GitHub 账号，先注册账号。SSH Keys 建议提前配置，否则每次提交或部署时都需要输入账号凭证。

开始安装Hexo

安装Hexo

Node.js 和 Git 都安装好后，可执行如下命令安装 Hexo：

1	npm install -g hexo-cli

初始化

然后执行 init 命令，把 Hexo 初始化到指定目录。进入目标目录后执行：

hexo init

至此，基础安装已经完成。

生成静态页面

进入 Hexo 初始化目录，执行如下命令，生成静态页面到 public 目录。

1	hexo generate

本地启动

启动本地服务，进行文章预览调试，命令：

1	hexo server

在浏览器中访问 http://localhost:4000。如果启动失败，可以参考下面的常见错误。

1	ERROR Plugin load failed: hexo-server

原因：

1	Besides, utilities are separated into a standalone module. hexo.util is not reachable anymore.

解决方法，执行命令：

1	npm install hexo-server --save

安装完成后，再次启动服务器。网站会在 http://localhost:4000 下启动。在服务器启动期间，Hexo 会监视文件变动并自动更新，无须重启服务器。
这个时候再重新生成静态文件，命令：

1	hexo generate

启动本地服务器：

1	hexo server

如果您想要更改端口，或是在执行时遇到了 EADDRINUSE 错误，可以在执行时使用 -p 选项指定其他端口，如下：

1	hexo server -p 5000

配置 GitHub

建立Repository

建立与你用户名对应的仓库，仓库名必须为 your_user_name.github.io。然后建立关联。假设博客在本地 /Users/chenhu/Documents/Hexo，目录中通常会包含：

1 2	_config.yml node_modules public source　　　　 db.json package.json scaffolds themes

接着修改 _config.yml 文件来建立关联：

1	vim _config.yml

翻到最下面，改成类似下面的配置：

deploy:
  type: git
  repository: https://github.com/chenhu1001/chenhu1001.github.io.git
  branch: master

执行如下命令安装 Git 部署插件：

1	npm install hexo-deployer-git --save

不同 Hexo 版本对部署插件和配置项的要求可能不同。本文示例基于 Hexo 3.2.2，如果版本较新，请以当前插件文档为准。
然后，执行配置命令：

1	hexo deploy

然后在浏览器中访问 https://chenhu1001.github.io。这里的 chenhu1001 需要替换成自己的 GitHub 用户名。

部署步骤

步骤

每次部署的步骤，可按以下三步来进行。

1
2
3

hexo clean
hexo generate
hexo deploy

还可以将上面的 3 个命令封装成一个 shell 脚本（publish.sh），放在 Hexo 对应的目录下方便部署。

一些常用命令：

hexo new "postName"   //新建文章
hexo new page "pageName"   //新建页面
hexo generate   //生成静态页面至public目录
hexo server   //开启预览访问端口（默认端口4000，'ctrl + c'关闭server）
hexo deploy   //将Hexo部署到GitHub
hexo help   //查看帮助
hexo version   //查看Hexo的版本
&emsp;&emsp;   //段落前空两格(为了显示，没有转移符)
<!--more-->   //用于文章的隔断，显示更多
[iOS,WebRTC,直播,FFMpeg]   //用于写文章时增加tag