Tutorial:基于Hexo框架的GitHub个人主页搭建教程（前篇）

一年前的暑假，笔者曾经对照着网上的教程，试着弄一个专属于自己的GitHub主页，但由于笔者对具体的技术细节不太熟悉，加之时间不太充裕，写作灵感又极其匮乏，于是套了个Material主题后就不了了之。

最近适逢疫情严峻，笔者无法顺利开展实验，于是决定重拾计算机的“老本行”，钻研一下如何搭建自己的GitHub主页。经过这一两天的努力，笔者终于完成了GitHub个人主页的搭建，接下来只需要对博客进行小修小补，并搞清楚版本管理与部署即可。

也许有人会问，按你的说法，用Hexo搭建GitHub个人主页，只需要一天搭框架，一天修故障，不是易如反掌的事？但换个角度想，笔者毕竟没有按部就班照着一份系统的教程来建主页，而是把网上的资料东拼西凑，才勉强搭了一个能用的，其中踩过的坑和绕过的远路，只有自己知晓。为了避免今后再费周折，笔者决定写下这篇教程，既是给自己准备一份建站的参考资料，也可以用来帮助其他初涉Hexo，希望用它搭建博客的爱好者。

既然这样，那……就开始了？

Part 0. Git是啥？GitHub又是啥？为啥要用GitHub做个人主页？

Git是一款基于快照（snapshot-based）的分布式版本控制（distributed version control）工具。“基于快照”意味着，当一个用户用Git更新文件（如一段代码）时，Git不会为每个文件保存一个版本，而是先计算文件的哈希码，并与之前的版本比较，如果哈希码相同，Git便会记下一个链接，这个链接指向上一个版本储存的文件，如果哈希码不同，Git则会创建一个快照，并保存这个快照的索引，如图0.1所示。

图0.1 Git的“基于快照”的版本控制思路

而“分布式”意味着，任何一个开发者，都可以在自己的电脑上，存储自己编辑的当前版本的文件，以及这些文件从创建，到每一次修改，最后变成现在的本地存储版本的过程。这样，即使开发者与（存储主干版本的）公共服务器断开连接，开发者仍然能用自己的电脑，对文件进行增删与修改，并且在本地提交版本更新，等到与公共服务器重连后，再提交pull request，然后与主干版本合并，从而大大提高了开发效率（见图0.2）。

图0.2 Git的“分布式”存储思路

虽然Git是分布式版本控制工具，但正如前面提到的那样，为了保证有一个稳定的主干版本，供不同的开发者下载与修改，必须要设立一台公共服务器，用以存储主干版本的文件。这台公共服务器，既可以由开发者亲自组装搭建，也可以来自于具有代码托管能力的商业公司（即Git server as a service），而GitHub便是其中历史悠久（2008年创立），规模最大（超过8千万的用户，超过2亿的代码仓库，其中开放仓库近3千万），也是最富盛名的Git服务平台，其简洁易用的界面、丰富的代码资源、友好的社区氛围，为搭建个人网站提供了极大的便利。

也许稍微懂行一点的朋友会问：为什么你这么推荐GitHub，而不推荐GitLab或Gitee呢？毕竟，如果不更换DNS，也不用校园网，GitHub很容易因为网络问题，无法拉取或上传代码，导致个人网页难以持续更新，而用GitLab或Gitee，则大概率可以避免这些问题。不错，GitHub确实有网络不畅的痛点（这个在之后的疑难解答中也会提及），然而把GitLab或Gitee当GitHub的代餐，遇到棘手问题的概率更大，找不到解决方案的概率也更大，因为互联网环境下，讨论GitHub使用方法的帖子和文章，远比讨论GitLab或Gitee的要多。

此外，像Gitee之类的国内Git服务平台，还存在两个头疼的问题：其一，这些平台更多面向国内用户，国际市场开拓不大，若决定常驻这些平台，便会错过许多来自国外开发者的优质代码，以及与这些国外开发者沟通交流，切磋技艺的机会；其二，向Gitee等国内平台提交代码后，由于平台的自我审核机制，这些代码基本上不能第一时间上传并展示在平台网站上，这就导致若是提交软件源码，其他用户并不能立即享受新版本软件的便利，若是提交个人博客的文章，其他用户也不能第一时间关注。鉴于这两点，笔者建议，如果GitHub能正常登陆，且能正常拉取/提交代码，仍应将GitHub作为代码仓库与个人网页的首选。

Part I. 前期准备：GitHub账号的申请，GitHub主页仓库的创建，以及本地Git环境的配置

注册个人GitHub账号，在其中创建GitHub主页对应的代码仓库

为了建立GitHub主页，首先我们要创建一个GitHub账号，并在这个账号中创建一个代码仓库，用于存储发布在GitHub主页的文章，以及运行GitHub主页所需要的代码。为此，我们在浏览器中访问GitHub.com，这将弹出图1.1所示的界面，点击右上角的“Sign up”按钮，GitHub将会自动跳转到注册页面。

图1.1 GitHub首页界面，注册按钮用红框标出

注册页面会提示输入邮箱，一般用自己经常使用的邮箱（学校邮箱、网易邮箱、QQ邮箱皆可）。

图1.2 GitHub注册界面，提示你输入邮箱

之后依次输入用户名和账号密码，点击确认，GitHub会发送认证邮件，我们只需打开邮箱，进入认证邮件，点击认证链接，即可完成注册。

注册后，我们登录GitHub账号，进入用户界面，点击右上角的加号（在你的缩略头像左侧），会弹出一个下拉菜单，点击“New repository”，就会转到代码仓库的创建页面，如图1.3所示。

图1.3 从GitHub用户界面创建代码仓库（对不起我是二次元）

我们给即将创建的代码仓库，命名为(your_username).github.io，此处的(your_username)应与当前登录的GitHub账号名称（不是昵称！）相同，此外，还要保证这个代码仓库勾选的是“Public”而非“Private”，这样其他人才能访问你的界面。确保选项无误后，点击下方的绿色按钮“Create repository”，GitHub就会生成GitHub主页对应的代码仓库。

图1.4 把即将创建的代码仓库命名为(your_username).github.io，注意到命名区为红色，表明同名仓库已被创建

在本地环境安装Git，并以SSH方式关联本地Git与GitHub

根据Part 0的描述可知，仅仅在GitHub申请账号和建立代码仓库，而没有建立本地的Git环境，或是建立了Git环境，却没有将其与GitHub关联，仍然不能把博客页面上传到GitHub部署。因此，我们要做的下一步工作，就是在本地计算机上安装Git，然后在Git bash中登陆自己的GitHub账号，最后配置SSH公钥，便于之后拉取或上传代码时，以SSH方式关联本地Git与GitHub。

Git的官方网站是https://git-scm.com/，进入页面后会有一个大大的“Downloads”，点进去就会跳转到下载界面。

图1.5 Git的官方网站，已标出下载入口

考虑到我们是在Windows下更新GitHub个人主页，这里我们直接点“Windows”，下载适用于Windows系统的Git套件。

图1.6 Git的下载界面，Windows用户点选“Windows”即可

下载完毕后，双击安装包运行，勾选“同意使用协议”，之后选项全部默认，一路点击Next，等待安装程序执行完毕后，点击“Finish”完成安装。

通常情况下，Git套件安装后便能立即使用，如果不放心，可以在命令行中输入git --version并执行，若弹出git version ×.×.×.windows.×，且与安装包对应版本一致，便说明Git组件安装成功。

图1.7 验证Git是否安装成功

有了Git组件，我们就可以用Git上传我们的博客文章，或是下载博客所需的主题文件，是不是离搭建GitHub个人主页又近了一步？不过别高兴太早，在正式搭建个人主页前，我们还要做一件非常重要的事，那就是在Git bash上登录自己的GitHub账号，并且为之后的登录配置SSH密钥。

那这里可能有人要问了，我每次拉取或提交代码，就想跟GitHub对着干，我偏偏不用SSH登录，就手动输入密码，可不可以？曾经很长一段时间，笔者就是这么做的，GitHub也默许通过密码登录，在本地Git与GitHub之间建立连接的行为。然而，2021年8月，GitHub宣布，不再支持通过GitHub账户密码验证本地Git操作，这意味着任用户一千个不同意，也得使用SSH方式登录，这或许就是大公司的威严吧……

无论如何，我们还是要打开Git bash，输入如下命令，登录你的GitHub账号，也让本地Git记住自己的GitHub用户名（对应于命令中的[your_username]）和注册邮箱（对应于命令中的[your_email]）：

git config --global user.name [your_username]
git config --global user.email [your_email]

要注意的是，第一次登录时，Git会提示你输入密码，但出于保密因素，除“Enter your password: ”这行系统提示消息外，命令行不会显示任何字符，也不会在你输入或删除字符时用增减星号（井号）表示，因此输入密码时，最好放慢速度，避免因打字过快而输错。

下一步是生成适用于本地计算机的SSH密钥，为此要输入以下命令并运行，其中[your_email]仍然代表你注册GitHub时使用的邮箱：

ssh-keygen -t rsa -C user.email [your_email]

此时会依次弹出如下提示，我们只需依次摁回车即可，不需要额外操作：

Enter file in which to save the key (/c/Users/tanglab_lzh/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

整个密钥生成过程如下图所示：

图1.8 在Git bash登录GitHub账号与生成SSH密钥

ssh-keygen会将生成的私钥文件id_rsa与公钥文件id_rsa.pub放在以下目录（如果没有该文件夹，ssh-keygen会自行生成一个），故只要找到用户文件夹，将其下的.ssh文件夹打开，便能找到id_rsa.pub：

C:\Users\(computer_username)\.ssh

用记事本打开id_rsa.pub，按Ctrl+A全选，再按Ctrl+C复制，然后按图1.9所示步骤，找到“SSH and GPG keys”选项卡，单击“New SSH key”，进入添加SSH密钥界面。

图1.9 找到“SSH and GPG keys”选项卡，进入添加SSH密钥界面

添加SSH密钥界面如图1.10所示，总计有三个框：“Title”代表密钥名称，一般用好记的名称表示；“Key type”代表密钥类型，有“验证密钥（Authentication key）”与“签名密钥（Signing key）”两种选项，此处保持“验证密钥”不动即可；“Key”为密钥内容，这是添加密钥的重点，我们把刚才从id_rsa.pub复制过来的内容粘贴到这个框，然后点选“Add SSH key”，生成的公钥就会添加到GitHub中。

图1.10 添加SSH密钥界面，其中的“Key”文本框要贴上id_rsa.pub的全部内容

最后，在命令行中输入如下命令，以SSH方式登录GitHub服务器：

ssh -T git@github.com

如果命令行跳出Hi [your_username]! You've successfully authenticated, but GitHub does not provide shell access.，说明SSH密钥配置正确，你可以利用本地Git套件拉取或上传代码到GitHub。而如果命令行频繁跳出Connection reset by [GitHub_SSH_IP] port 22，则有可能是国内不可言说的网络环境所致，多尝试几次，或改用移动热点连接，或将端口切换至443，有可能改善此类情形。

图1.11 验证本地计算机能否通过SSH访问GitHub，注意到GitHub的22端口多次拒绝访问，可能与网络环境有关，为此笔者将登录端口切换至443

Part II. Node.js环境的安装，以及Hexo框架的初步搭建

在Windows系统安装Node.js，并设置国内更新源

建立好GitHub主页仓库，并在本地配置好Git环境后，我们就可以依次安装Node.js和Hexo框架了。考虑到笔者主要在Windows上撰写博客文章，故以Windows环境为例，介绍Node.js和Hexo的安装流程，其他系统（如Mac OS X和Linux）的安装流程，可以参考Hexo中文文档，这里暂不展开论述。

访问Node.js官方网站（如果无法访问，可以访问npmmirror中国镜像站的Node.js镜像），在“Windows Installer”一行，根据系统的位数点选（一般选64位下载，如图2.1所示），浏览器就会将对应位数的Node.js安装包下载到本地。

图2.1 Node.js官方网站的下载页面，Windows用户通常点选64位安装包即可

双击安装包运行，勾选“同意使用协议”，之后选项全部默认，一路点击Next，等待安装程序执行完毕后，点击“Finish”完成安装。

为确保Node.js的所有组件均已正常安装，我们要打开命令提示符（Windows Powershell或Windows Terminal亦可），分别输入如下命令并运行：

node -v
npm -v

如果分别跳出安装包对应的版本号（如图2.2所示），说明Node.js成功安装，否则应卸载Node.js，重新运行安装包进行安装。

图2.2 成功安装Node.js后，查询node和npm的版本号，会得到与安装包一致的结果

考虑到国内与Node.js软件包服务器的连接极不稳定，笔者推荐将npm源替换为npmmirror镜像源（即原阿里源，个中关系参见疑难解答的“Node.js与Hexo部分”），这一步骤非常简单，只需在命令行输入下列命令，回车执行即可：

npm config set registry https://registry.npmmirror.com

当然，npmmirror还提供了另一种换源方法，就是用npmmirror定制的包管理工具cnpm代替npm，具体命令为：

npm install -g cnpm --registry=https://registry.npmmirror.com

不过，笔者对cnpm并不熟悉，导致在后续的hexo安装时频频报错，最后决定放弃使用cnpm，改回原生的包管理工具npm。此外，也有知乎网友指出，换用cnpm后，因为cnpm奇葩的存放位置（hexo的软连接没有放在/usr/local/bin，而是放在/var/root/.npm-global/lib/node_modules/hexo-cli/bin），导致即使正确安装hexo-cli，也找不到hexo命令。综合以上两点，笔者建议直接用npm config更换npm源，而非采用cnpm来换源（毕竟安装cnpm时也要修改registry）。

在本地部署Hexo框架，生成初始GitHub主页

接下来，在你的工作区中，创建一个新文件夹，用以存放发布在GitHub主页的文章，以及运行GitHub主页所需要的代码（比如笔者就将其放在C:\Workbench\chemlzh.github.io）。然后，运行命令行（如果文件夹在C盘上，一定要以管理员权限运行命令行！否则没有读写权限！），并跳转到刚创建的文件夹。之后，输入下列命令，安装hexo的客户端版本：

npm i hexo-cli -g

正常安装后，命令行通常会输出如下提示

hexo-cli@(version-number)
added ×× packages from ×× contributors in ××s

或是如下提示

All packages installed (×× packages installed from npm registry, used ××s(network ××s), speed ××MB/s, json ××(××kB), tarball ××MB)

如果没有看到类似于上述的提示，而是弹出红色或棕黄色的提示，并含有“error”、“unsuccessful”等字样，则表明hexo-cli没有安装成功（此时要么没有换成国内源，要么在安装过程中出现了强制中断、环境漏配等问题）。

确保hexo-cli安装成功后，依次输入以下命令并运行，让npm在新文件夹中初始化hexo环境，同时安装运行的必要组件：

hexo init .
npm install

如果hexo的环境变量配置正确，运行上述命令后，新文件夹中会成功生成如下文件：

.
./_config.yml  # 网站配置信息
./package.json # 在后续修改中安装的npm包的信息
./package-lock.json # 初始化hexo环境时安装的npm包的信息
./scaffolds # 模板文件夹
./source # 用户文件夹，存放博客文章、图片等
./source/_draft # 存放尚未发布的草稿
./source/_posts # 存放正式发布的文章
./themes # 主题文件夹

最后，输入如下命令并依次运行，随后在浏览器中打开http://localhost:4000，便能在本地看到自己的博客界面。

hexo g
hexo s

不过，由于是首次创建，且尚未添加任何主题模板，因此显示的是hexo默认风格界面，且归档文章中只有一篇“hello world”。

图2.3 首次创建hexo环境时，在本地显示的博客界面（图片引自随风的文章）

备注：如果按Windows 下 Node.js 的安装图文教程，修改了包存放路径，那么在运行hexo init .时，将会提示“hexo”命令不存在。此时，应依次打开“Windows设置”→“系统”→“关于”→“高级系统设置”→“环境变量”，将hexo-cli目录下的bin添加至PATH中（以笔者为例，便是在全局变量的PATH中，添加一条C:\Program Files\nodejs\node_global\node_modules\hexo-cli\bin），然后点击“确定”。随后，重新打开终端（若提示无读写权限，需以管理员身份打开），进入博客文件夹，重新运行hexo init .，此时该文件夹将正常生成hexo框架文件。在大部分情况下，该策略对未修改npm包存放路径，但提示“hexo”命令不存在的情形也有效（尚未测试）。

Part III. 将Material主题应用到GitHub个人主页

为什么不采用Hexo的默认主题，而采用自定义主题？

请诸位回到Part II的结尾部分，看一看Hexo的默认风格界面吧。诚然，这个界面以白色与灰色为主色调，没有东拼西贴的小广告，与10-20年前绝大多数网站相比，可谓是简洁清爽。但仔细一想，总感觉缺了点什么——或许，对某些人而言，默认界面缺的是鲜明的色彩，扁平化的界面设计；或许，对某些人而言，默认界面缺的则是黑白的对比，棱角分明的冷艳感。

除渲染风格较为乏味外，Hexo的默认风格界面，还缺了许多有意思的功能选项：例如，我想给每篇文章加一张亮眼的题图，可是默认界面的文章根本不会显示题图；我想把归档日志和最近发表折叠到边栏，可是默认界面显示的是顶栏，而且主界面中并没有把归档日志收纳起来……

显然，建站者日益增长的审美与实用需求，与默认主题较为贫瘠的生产力之间，产生了巨大的矛盾，这促使广大的开发者对Hexo主题进行个性化修改，自定义主题因此诞生。

想要色彩鲜明的扁平化设计？Material主题就很适合你：

图3.1 Material主题演示页（原网页见此）

想要遵循KISS原则的教诲，在黑白二色间自由翱翔？那就尝试一下NexT主题：

图3.2 NexT主题演示页（原网页见此）

甚至，看官想来点二次元？也有大手子做好了明日方舟主题：

图3.3 Arknight主题演示页（原网页见此）

可以说，除了极其个性化的设计外（这得自己动手丰衣足食），任何你想到的界面风格，都可以在GitHub上找到对应的主题源码，只要正确的下载与安装，再加上适当的调参，便能将单调的Hexo初始页面，打造为炫酷的个人主页！

好了，废话少说，让我们看看怎么在初始的Hexo框架上，添加Material主题吧。至于为什么要采用Material主题，笔者在这一节的结尾给出了充分的理由，请诸位务必往下阅读哦！

如何添加Material主题

Material主题目前由iblh等人开发与维护，其所有发布版本均可从GitHub Releases中获取，这里我们由两种选择：一是下载发布较早，但Bug较少的1.5.2版本，二是下载最新发布，但存在较多Bug的1.5.6版本。如果是Hexo新手，建议下载1.5.2版本，以避免之后生成页面失败的问题；如果对自己的编程纠错能力有一定把握，可以选择1.5.6尝鲜。进入GitHub Releases，点击“Source code (zip)”，就会自动下载对应版本的Material主题包，如图3.4所示

图3.4 在Releases页面下载1.5.6版Material主题包（旧版本下拉即可找到）

将下载的1.5.6版Material主题包解压缩，得到一个叫“hexo-theme-material-1.5.6”的文件夹，考虑到我们不需要标注版本号，故更名为“hexo-theme-material”。然后，打开本地个人主页的根目录，找到“themes”文件夹并进入，再将“hexo-theme-material”复制到“themes”文件夹下。

图3.5 进入博客根目录的“themes”文件夹，将更名后的Material主题文件夹复制到“themes”下

刚刚解压的Material主题包，还没有添加任何格式设置，因此我们要打开themes/hexo-theme-material，找到_config.template.yml，并在原地拷贝一份，旧有的_config.template.yml保持原样（或改名为_config.template_duplicated.yml，以防与根目录下的_config.template.yml冲突），新拷贝的改名为_config.yml，它代表针对Material主题的设置（而非Hexo框架的设置）。

之后，我们回到个人主页的根目录，打开其下的_config.yml（代表Hexo框架的设置，注意不要与主题文件夹下的_config.yml混淆），修改图3.6红框所示的内容。其中，title代表个人主页的标题；author代表博客文章的默认作者；language代表网页界面默认使用的语言文字，中文用户一般填“zh-CN”即可；url为博客网址，对于GitHub个人主页而言，如果不额外绑定域名，一般为https://(your_username).github.io/。

图3.6 编辑个人主页根目录_config.yml的部分参数

最后，我们下拉到theme:选项，填入放在themes文件夹下的Material主题包的名字（此处为“hexo-theme-material”），如图3.7所示，便可以保存_config.yml并退出了。

图3.6 在根目录_config.yml中启用Material主题

回到个人主页的根目录，点下右键，选择菜单中的“Git bash here”，启动Git bash，依次输入以下命令并运行。

hexo clean # 清除public文件夹下的所有文件
hexo g # 将网页生成在public文件夹下
hexo s # 启动本地服务器预览

如果使用的是1.5.2版，网页源代码将会正常生成，此时，在浏览器中打开http://localhost:4000，应该就能得到与图3.1相似的网页界面了。（如果是1.5.6版，可以参考疑难解答的“Material主题部分”，修改/(your_blog_name)/themes/hexo-theme-material/layout/_widget下的dnsprefetch.ejs，然后重新生成网页）

注意：修改_config.yml时，一定要注意书写格式！首先，选项名称后的冒号一定得是英文的冒号:，而不是中文的冒号：。其次，选项名称与冒号之间没有空格，而冒号与后面的选项取值之间，则有一个半角空格。任何没有按照上述标准添加或修改的选项，其导致的无法生成网页的html代码等后果，均由修改者承担！

私货：为什么选择了Material主题？

太长不看版：因为NexT主题太过朴素，适合于程序员总结经验，却不适合于向他人展示成果；而Material主题色彩鲜明，界面扁平化，还能给每篇文章添加自选题图。

详细解释：如果你搜索“常用/好看的Hexo主题”，十有八九会有人力荐NexT主题，因为它界面简洁，只有黑白两种配色，没有多余的按钮，也没有冗杂的颜色，非常适合程序员阅读。而从GitHub的Star数看，最受欢迎的Hexo主题，NexT当之无愧（新版本7.8K，作为对比，Material主题的Star数为4K）。不过，从调动阅读兴趣的角度看，黑白配色也是一把“双刃剑”——任何枯燥的技术性内容，搭配上一眼望不到头的白底黑字或黑底白字，都将是效果拔群的“催眠模因”，刚开始可能还不太在意，读了5-10分钟才发现：这篇文章怎么还没结束！太无聊了，不看不看！

相反，Material主题运用了多种饱和度较高的颜色，且色彩搭配非常和谐，这在一定程度上减轻了阅读的困倦感；扁平化的设计风格，则将杂乱无章的超链接，统一为方正而易于识别的按钮，有一种规整、轻盈的“赛博美感”。此外，Material还为每一篇文章，添加了随机选取的题图。倘若博主觉得不太满意，还能结合第三方插件，将题图更换为萌萌哒的二次元同人图，既提升了阅读效率，又能温暖一下阿宅孤单的心灵呢（笑）。

（当然，也有人认为，色彩过于鲜艳，或是添加的二次元同人图太多，时间长了反倒会有生理与精神上的双重疲劳，因此不喜欢花花绿绿的风格。这个问题仁者见仁智者见智，至少对于我而言，NexT风格的网页不太能调得动我的兴趣）

参考资料

Part 0：

版本控制工具(CVS、SVN、GIT)简介

Part I：

Git 远程仓库(Github)

Github 简明教程

Git password authentication is shutting down

Part II：

Hexo中文文档

Windows 下 Node.js 的安装图文教程

安装hexo 提示 command not found，怎么解决？

Part III：

Material Theme Docs

hexo-theme-material | Easy Hexo

有哪些好看的 Hexo 主题？

Hexo 好看的主题推荐