教程（二）hexo框架的搭建及部署

这篇做完，你的 Hexo 博客会先在本地 http://localhost:4000/ 跑起来，再部署到 GitHub，用“xxx.github.io”就能访问。前提是已经按上一篇建好了“用户名.github.io”仓库，并记下了它的 HTTPS 链接。

先装 node.js

用 Hexo 需要 node.js。它是什么？

我们要是不想让浏览器事必躬亲，那就把活扔给服务器干；服务器一下子要服务很多浏览器时，就不能认死理非要串行操作，要灵活统筹，同时开始几件事，哪件完事关闭哪件。这三个特征用江湖切口说就是：

• 服务器端JavaScript处理：server-side JavaScript execution
• 非阻断/异步I/O：non-blocking or asynchronous I/O
• 事件驱动：Event-driven

Node.js 就是这样一个服务器端的、非阻断式 I/O 的、事件驱动的 JavaScript 运行环境，重要的是，它是开源的。

安装参考：安装node.js教程。这篇菜鸟教程除了安装，还介绍了 node.js 本身和常用的开发功能，有兴趣可以看看。

装好以后靠 npm 来用它。NPM 是随 NodeJS 一起安装的包管理工具，能解决 NodeJS 代码部署上的很多问题，常见用法有：

• 从 NPM 服务器下载别人写的第三方包到本地使用。
• 从 NPM 服务器下载并安装别人写的命令行程序到本地使用。
• 把自己写的包或命令行程序上传到 NPM 服务器供别人使用。

部署 Hexo 就是用 npm 下载 Hexo 的安装包，能省下大量时间。

今天装 Node，我会提醒两件事。一是选 LTS 版：官方下载页默认给的就是 LTS，发布说明也写明生产环境只该用 Active LTS 或 Maintenance LTS。二是 npm 官方强烈建议用 nvm 这类版本管理器来装，因为用安装包装的话，以后 npm install -g 很容易撞上权限错误。

安装并初始化 Hexo

1. 在终端（cmd 也行）里安装 webpack：

npm install webpack -g

WebPack 可以看作模块打包机：它分析你的项目结构，找到 JavaScript 模块和其他浏览器不能直接运行的拓展语言（Scss、TypeScript 等），打包成合适的格式供浏览器使用。

回头看，这一步其实可以跳过。Hexo 官方的安装前提只有 Node.js 和 Git，hexo init 之后默认装好的是 EJS、Stylus、Markdown 几个渲染器，没有任何打包器，webpack 跟 Hexo 生成网页的链路没有关系。多装一个全局包，只是多一处可能报错的地方。

2. 进入选好的 git 仓库，也就是和 GitHub 上建好 github pages 关联的那个仓库，准备一个空文件夹，可以叫 blog 或任何你喜欢的名字，在终端里进入这个目录。
3. 下载 Hexo 并初始化：

npm install -g hexo-cli
hexo init

现在官方的写法是 hexo init <folder> 建一个新目录，再 cd <folder> 进去执行 npm install，见 Hexo 文档的“建站”。

npm install -g hexo-cli 在 Linux 和 macOS 上如果报 EACCES，就是上面说的权限问题。npm 官方给了两种解法：用 nvm 重装 Node（推荐），或者 npm config set prefix ~/.local 把全局目录挪到自己家目录，再把 ~/.local/bin 加进 PATH。实在不想动全局环境，也可以在博客目录里本地装 npm install hexo，之后用 npx hexo <命令> 调用。

我的文件夹叫 blog。运行完上面的命令，文件夹里应该有下图中除了主题配置文件 _config.butterfly.yml 之外的所有文件：

看到一样的画面，说明 Hexo 已经装在你的电脑上了，稍微配置一下就能运行博客。

在本地跑起来

还是在这个目录下，依次输入：

1. 静态部署命令：

hexo g

2. 启动本地服务器，以后调试也用它：

hexo s

终端应该会提示这样的信息：

这说明服务器启动成功，可以通过 4000 端口访问静态网页。在浏览器输入 http://localhost:4000/，会看到这样的画面：

到这里博客已经可以在本地用了，接下来把它部署到 GitHub。

部署到 GitHub

1. 找到 Hexo 目录下的配置文件 _config.yml：

2. 打开文件，把底部的信息补完整：

deploy:
  type: git
  repository: https://github.com/blankhoney/blankhoney.github.io.git  #你的仓库地址
  branch: main

注意：GitHub 的主分支之前已经改为 main，继续用 master 可能会在接下来的步骤中报错。

更准确地说，branch 要填你仓库实际存在的分支。GitHub 只把新建仓库的默认分支改成了 main，老仓库不受影响，Hexo 的 GitHub Pages 指南也写着老仓库可能还是 master。出错多半是填的分支在远端不存在，或者 Pages 的发布源选了另一个分支。

仓库地址在 GitHub 仓库的这个位置：

3. 在 Hexo 目录（以后简称根目录）下安装 git 部署插件：

npm install hexo-deployer-git --save

4. 安装成功后依次输入：

hexo clean   #清除缓存文件 db.json 和已生成的静态文件 public
hexo g       #生成网站静态文件到默认设置的 public 文件夹(hexo generate 的缩写)
hexo d       #自动生成网站静态文件，并部署到设定的仓库(hexo deploy 的缩写)

没报错就是部署成功了；报错的话，看报错位置和报错信息去改。

hexo d 到底做了什么

部署插件 hexo-deployer-git 做的事，是把 public 里生成好的网页提交一次，再用 git push --force 推到你填的分支。GitHub Pages 那边认的是发布源分支的根目录（也可以选 /docs），推上去就自动发布。

知道这一点，几个常见困惑就好解释了：

• 别在 GitHub 网页上直接改部署分支里的文件。下次 hexo d 会强推覆盖，改动不会留下。
• 推成功了打开还是 404，先去仓库 Settings → Pages 看发布源选的是不是你配置里写的那个分支。Hexo 文档也提醒过，要把仓库默认分支设成 _config.yml 里的分支名。
• 绑自定义域名用的 CNAME 文件要放在 source 目录，才会跟着一起推上去。
• 部署时弹出用户名密码框，是因为仓库地址用了 HTTPS。账号密码现在已经不认了，要填 token，或者把地址换成 SSH 形式，上一篇讲过。

报错了先对一下这张表

“看报错信息去改”说起来容易。Hexo 官方疑难解答里，和这篇步骤对得上的有这几条：

5. 打开浏览器，输入 https://xxx.github.io 就能打开你的网页：

这是我配好主题之后的画面。你看到的还会是最初的博客画面，但这已经说明部署成功了：

现在官方推荐的是 GitHub Actions

如果今天从头搭，我会考虑换条路。Hexo 自己的 GitHub Pages 指南已经把主推流程换成了 GitHub Actions，上面这套 hexo-deployer-git 退成了备选，依旧能用。

Actions 这条路的思路是：博客源码整个推到仓库，构建交给 GitHub。

1. 仓库 Settings → Pages → Source，把发布源改成 GitHub Actions；
2. 在博客根目录建 .github/workflows/pages.yml，内容照 Hexo 指南里给的模板抄；
3. 以后只管 git push 源码，GitHub 会自己构建并发布。

GitHub 的文档要求部署这一步带 pages: write 和 id-token: write 权限，自己改模板时别删掉。我看中的好处是源码和网页不用分两处管，换电脑也不用在本地装全套环境才能发文章。

下一步：写文章或者换主题

现在已经可以开始写博客、上传了。想美化博客的话，可以参考我的下一个教程。我用的是 butterfly 主题，官方美化教程在这里：博客主题美化butterfly