如何用GitHub和hexo搭建一个属于自己的博客?

2024年5月1日更：目前GitHub的版本一直在变，需要诸君看情况而变，此教程不是那么的“傻瓜”（我的锅，都是我的锅）如有什么问题还请问我。

（重要）：您可能遇到许许多多的问题。请不要慌张，您可以[在这里](如何用GitHub和hexo搭建一个属于自己的博客? | Finder)或者拉动到文章的最后面的“6.常见问题”来寻找方案（由于系统差异，他们可能不完全相同，请周知）。您还可以询问人工智能如ChatGPT，或通过使用搜索引擎来寻找解决方法。最后您可以向我发送电子邮件来解决问题。

1.前言

<1>.为什么要用hexo搭建一个属于自己的博客?

自由:现在入博客园,CSDN,微信公众号等,都可以直接发表同时百度等也可以直接搜索到,但是不自由,会受到平台的各种限制和广告。

拥有性:文章写完是在您的手上的，不像微信公众号等，若要想复制发在其他平台上，可能复制的不顺畅，图片无法复制。我之前微信公众号写了不少的文章，现在想迁移过来就十分麻烦。

<2>.为什么要用GitHub Page

没钱，没钱，还是没钱

一个域名服务器，短暂的可能并不是很贵，但是长时间钱就多了，并且未来维护要比GitHub Page麻烦的多

<3>.为什么要写这篇文章

1.为了大家可以方便地搭建自己的网站

2.为了自己每次重装系统后再配置更方便一些

2.Hexo简介

实际上hexo官网写的不是特别的好，教程比较老，但是还是有参考价值的。此文章部分内容来源于hexo官网。

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。（来源官网简介）

3.开始使用Hexo

<1>安装环境

• Node.js (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本)

  • Node.js 为大多数平台提供了官方的 安装程序。如果您在中国大陆地区，您可以前往 淘宝 Node.js 镜像 下载。（本人未亲自尝试）

    Windows 用户
    使用 Node.js 官方安装程序时，请确保勾选 Add to PATH 选项（默认已勾选）

    Mac / Linux 用户
    如果在尝试安装 Hexo 的过程中出现 EACCES 权限错误，请遵循 由 npmjs 发布的指导 修复该问题。强烈建议 不要 使用 root、sudo 等方法覆盖权限（来源官方文档，未做测试）

    Linux
    如果您使用 Snap 来安装 Node.js，在 初始化 博客时您可能需要手动在目标文件夹中执行 npm install。

  其它的安装方法
  Windows：通过 nvs（推荐）或者 nvm 安装。
  Mac：使用 Homebrew 或 MacPorts 安装。
  Linux（DEB/RPM-based）：从 NodeSource 安装。

  P.S.对于 Mac 和 Linux 同样建议使用 nvs 或者 nvm，以避免可能会出现的权限问题。

• Git

  • Windows：下载并安装 git.

  • Mac：使用 Homebrew, MacPorts 或者下载 安装程序。

  • Linux (Fedora, Red Hat, CentOS)：终端输入sudo yum install git-core

    Mac 用户
    一定要安装Xcode，否则很可能出现问题，可以在App Store 安装 Xcode，Xcode 完成后，启动并进入 Preferences -> Download -> Command Line Tools -> Install 安装命令行工具，或者终端台输入命令：xcode-select --install(安装完Xcode可能就不需要安装git了？——2024年8月19日更，是的)

    Windows 用户
    对于中国大陆地区用户，可以前往 淘宝 Git for Windows 镜像 下载 git 安装包。

提示：Windows版本在安装这一步时，您可以勾选“(NEW!) Add a Git Bash Profile to Windows Terminal”在Windows的终端中直接使用Git Bash的指令。

可以通过终端输入

node -v
npm -v 

来查看是否安装成功及其版本号

<2>开始安装

以下的“$”只是为了证明是终端命令，大多情况下是不需要输入“$”这个符号的

macOSsudo之后会输入密码，密码不会显示，输入完按回车即可

1.安装基本内容

在终端台输入$ npm install -g hexo-cli

macOS和Linux用户：sudo npm install -g hexo-cli

可能存在的问题，请见此处

提示：Windows下您可以开启管理员模式后运行来解决其他奇奇怪怪的问题

2.初始化Hexo

cd到您想要安装的文件夹(macOS用户可以拖拽，Windows和linux可以直接cd，Windows下如果是Windows PowerShell可以尝试cd后直接接路径名)

输入hexo init myblog“myblog”是您要创建的文件夹的名称，这会创建一个文件夹并包含一些文件。

包含的文件有：

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

cd到hexo创建的文件夹

如果您已经有现成的了，完全可以把刚才的“输入hexo init myblog步骤忽略”

输入$npm install

方便复制，后面不写$了

macOS：sudo npm install

如果提示

added 1 package, and audited 237 packages in 1s

19 packages are looking for funding
  run `npm fund` for details

4 vulnerabilities (2 high, 2 critical)

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

输入

npm audit fix --force

我在Windows客户端注意到输出是“To address all issues, run:
npm audit fix”。如果是这样，那么您需要按照提示输入“npm audit fix”。请您记住要根据实际情况来确定，如不清楚可以查询网络或者电邮我。

3.相应作用

_config.yml

网站的 配置 信息，您可以在此配置大部分的参数。

package.json

应用程序的信息。EJS, Stylus 和 Markdown renderer 已默认安装，您可以自由移除。

package.json{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": ""
  },
  "dependencies": {
    "hexo": "^3.8.0",
    "hexo-generator-archive": "^0.1.5",
    "hexo-generator-category": "^0.1.3",
    "hexo-generator-index": "^0.2.1",
    "hexo-generator-tag": "^0.2.0",
    "hexo-renderer-ejs": "^0.3.1",
    "hexo-renderer-stylus": "^0.3.3",
    "hexo-renderer-marked": "^0.3.2",
    "hexo-server": "^0.3.3"
  }
}

scaffolds

模版 文件夹。当您新建文章时，Hexo 会根据 scaffold 来建立文件。

Hexo的模板是指在新建的文章文件中默认填充的内容。例如，如果您修改scaffold/post.md中的Front-matter内容，那么每次新建一篇文章时都会包含这个修改。

source

资源文件夹是存放用户资源的地方。除 _posts 文件夹之外，开头命名为 _(下划线)的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去。

themes

主题 文件夹。Hexo 会根据主题来生成静态页面。

4.开启服务

cd到hexo的文件夹（重要）

终端输入：(Mac相同)

hexo c
hexo g
hexo server

可能存在的问题，请见此处*（以下将不会再次提及）

此刻您应该在终端台看到一个网址，打开它，您会看见网站最初始的样子

如果您使用Windows，您可能会遇到这个窗口在第一次，您可以全部勾选“公共网络”和“私人网络”（特殊场合请注意）。当然它们是可以在之后被修改的。您可以参考这篇文章在 Windows 中将 Wi-Fi 网络设置为公共或专用网络 - Microsoft 支持

是不是很兴奋？（我这步做了很多次每到这个时候我也很激动啊哈哈）

4.Github创建仓库

1.创建一个GitHub账户

1.打开Github

2.点击Sign up

3.Enter your email的意思是输入您的电子邮件，即输入您的邮件

题外话：我记得我注册的时候也没有这么炫酷啊，现在注册页面时越来越好了

4.Create a password的意思是创建密码，输入一个密码

5.这里的意思是您想通过电子邮件接收产品更新和公告吗？

键入“y”表示为是，或键入“n”表示为否

看情况选择

6.完成验证

7.去邮箱查看验证码，如果没有，看看是不是没有连接上互联网（如果您在中国大陆，且使用中国大陆邮箱可能需要关闭代理才能连接），并检查垃圾邮箱。

8.这里是一个调查，应该都能看明白吧

9.这里的问题是：您有兴趣使用哪些特定功能？

选择所有适用的选项，以便我们可以向您指出正确的GitHub计划。

看着填（可以都不填）

10.这里是一个服务，我们选择免费的就好

11.后面略（实际上我是不小心关了浏览器）

2.GitHub仓库创建

1.打开Github

2.点击“New”

3.创建一个您的用户名并在用户名后加github.io的仓库，只有这样，将来用GitHub page创建博客的时候，才会被识别，也就是yourname.github.io，其中yourname就是您GitHub的用户名。（请放心，创建完的网页链接像我的博客链接一样）

这里因为我已经创建完成，所以不能创建了

4.Description (optional)是描述，自己填写

5.（可选）点击Add a README file（添加一个”读我“的文档（了解文档））

6.点击Create repository

5.继续使用Hexo

1.上传您的GitHub用户名和邮箱

1.回到终端台

（别忘了cd到hexo的文件夹）

您可能需要通过“Ctrl+C”快捷键的方式（macOS,Linux同理）来结束上一步的“开启服务”

git config --global user.name "yourname" 
git config --global user.email "youremail" 

快速操作小方法：您可以打开一个您信任的文本编辑器（如系统自带的）。然后创建文件把它们复制到文本编辑器后修改需要修改的内容之后再复制到终端台

yourname是GitHub名称，yourmail是您登入GitHub的邮箱

提示：可以输入以下内容确定您有没有输对

git config user.name 
git config user.email 

2.创建SSH文件

关闭窗口重新打开，然后cd到hexo的文件夹（目的是退出root状态，避免生成SSH文件时没有生成到用户文件夹里面，Windows用户应该不需要处理这个问题，当然这个也是一个坑）

ssh-keygen -t rsa -C "youremail" 

一路回车（不用管）

注：即使要求您输入密码，也不用管，直接回车（如图所示）

这里已经提示了SSH密钥的位置（不同电脑不同用户不同位置）

打开这个位置（可能需要显示隐藏文件，Mac用户按“Command+Shift+。”显示隐藏文件，Windows略，因为可以在直接在“文件管理器”中复制地址跳转(macOS好像也行？)如果您是复制地址跳转记得是复制到SSH的父文件夹）

SSH简单的说就是公钥加密，私钥解密，id_rsa是私钥，不能泄漏的，id_rsa.pub 是公钥，可以传给别人。把公钥放在GitHub上，这样当您连接GitHub账户时，它就会公钥加密，私钥解密，如果密钥无误，才能顺利的通过git上传您的文件到GitHub上。

3.上传公钥到GitHub

1.打开Github

2.点击Settings

3.点击SSH and GPG keys

4.点击New SSH key

5.把id_rsa.pub里面的内容复制进去（最后的邮箱名不要忘了）。

注：您可以用“文本编辑”打开，Windows类似

标题（Title）随便

6.回到终端台

（别忘了cd到hexo的文件夹）

输入ssh -T git@github.com 来查看是否成功

这里需要输入yes

4.关联hexo和GitHub

1.在hexo的根目录下，找到_config，打开它，在最后几行

添加：

deploy:
  type: git
  repo: https://github.com/YourgithubName/YourgithubName.github.io.git
  branch: main

因为GitHub把默认的分支（branch）名称由master改成了main，所以这里的branch也要改为main，但是网上的教程几乎全是master，一个坑

4.部署

1.回到终端台

（别忘了cd到hexo的文件夹）

2.输入

2024年五月一日更：如果您严格按照我的教程，因为前面关掉的已经被提权的sudo终端台，所以您应该在下面这个命令前加sudo（您所看到的版本已经是添加完毕的了）

sudo npm install hexo-deployer-git --save

Windows不需要在这里sudo

npm install hexo-deployer-git --save

3.输入

hexo clean
hexo generate
hexo deploy

可能存在的问题，请见此处

5.部署命令解读

hexo clean

清除缓存文件 (db.json) 和已生成的静态文件 (public)。

在某些情况（尤其是更换主题后），如果发现您对站点的更改无论如何也不生效，您可能需要运行该命令。

hexo generate

生成静态文件。

选项	描述
-d, --deploy	文件生成后立即部署网站
-w, --watch	监视文件变动
-b, --bail	生成过程中如果发生任何未处理的异常则抛出异常
-f, --force	强制重新生成文件 Hexo 引入了差分机制，如果 public 目录存在，那么 hexo g 只会重新生成改动的文件。 使用该参数的效果接近 hexo clean && hexo generate
-c, --concurrency	最大同时生成文件的数量，默认无限制

该命令可以简写为

hexo g

hexo deploy

部署网站。

参数	描述
-g, --generate	部署之前预先生成静态文件

该命令可以简写为：

$ hexo d

deploy需要输入GitHub账户和密码

输入GitHub密码时您可能会注意到报错了，这又是一个坑

官方解释：[Git password authentication is shutting down - GitHub Changelog

大致意思就是正常的密码在2021年8月13日后就不可用了，需要申请专门用于终端的“密码”

2024年8月更：现在你用Windows

6.创建专门“密码”方法

1.打开Github

2.点击Settings

3.点击Developer settings

4.点击Personal access tokens，然后点击Generate new token

2024年8月注：在两个二级菜单中选择“Tokens(classic)目前就可以”

5.Note随便，Expiration（到期）建议设置为未过期（No expiration）

权限建议全选，不过如果您只用于在终端台中Push的话，可以只选择最上面的所有的“repo”。之后点击Generate token

之后一会看到密钥，请立刻保存，无法显示第二次！！！！！

教程短暂完结，未来持续更新

6.常见问题

<1>上传失败

FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
Error: Spawn failed
    at ChildProcess.<anonymous> (/Users/yourusername/hexo/node_modules/hexo-util/lib/spawn.js:51:21)
    at ChildProcess.emit (node:events:513:28)
    at Process.ChildProcess._handle.onexit (node:internal/child_process:291:12)

可重新上传

<2>下载hexo框架失败

npm error code ECONNRESET
npm error syscall read
npm error errno ECONNRESET
npm error network request to https://registry.npmjs.org/hexo-cli failed, reason: read ECONNRESET
npm error network This is a problem related to network connectivity.
npm error network In most cases you are behind a proxy or have bad network settings.
npm error network
npm error network If you are behind a proxy, please make sure that the
npm error network 'proxy' config is set properly.  See: 'npm help config'
npm error A complete log of this run can be found in: C:\Users\yourusername\AppData\Local\npm-cache\_logs\2024-08-19T08_30_48_800Z-debug-0.log

基本可以确定是网络的问题，您可以再次尝试或者更换网络环境。

<3>开启服务失败

PS D:\Users\Yourusername\Documents\hexo> hexo c
hexo : File C:\Users\Yourusername\AppData\Roaming\npm\hexo.ps1 cannot be loaded because running scripts is disabled on this system. For
more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ hexo c
+ ~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess
PS D:\Users\Yourusername\Documents\hexo> hexo g
hexo : File C:\Users\Yourusername\AppData\Roaming\npm\hexo.ps1 cannot be loaded because running scripts is disabled on this system. For
more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ hexo g
+ ~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess
PS D:\Users\Yourusername\Documents\hexo> hexo server
hexo : File C:\Users\Yourusername\AppData\Roaming\npm\hexo.ps1 cannot be loaded because running scripts is disabled on this system. For
more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ hexo server
+ ~~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

我询问了ChatGPT这个问题。回答还算可以（中英双版本均为ChatGPT提供的）

这个错误是由于 PowerShell 的执行策略阻止脚本运行。你可以通过更改执行策略来解决这个问题。具体步骤如下：

1.以管理员身份打开 PowerShell:
  右键单击开始菜单，选择“Windows PowerShell (管理员)”或者“Windows Terminal (管理员)”（如果你使用的是 Windows Terminal）。

2.检查当前执行策略:
    运行以下命令来查看当前的策略：

Get-ExecutionPolicy

     你可能会看到 Restricted，这意味着脚本不能运行。

3.更改执行策略:

Set-ExecutionPolicy RemoteSigned

      系统可能会提示你确认更改。如果是，请输入 Y 并按 Enter 键。

4.重新运行 Hexo 命令:
现在可以重新尝试运行你的 Hexo 命令（如 hexo c、hexo g、hexo server）。

执行策略解释:

    Restricted: 不允许运行任何脚本。Windows PowerShell 只能以交互模式使用。
    RemoteSigned: 从互联网下载的脚本必须由受信任的发布者签名才能运行。
    Unrestricted: 没有任何限制，可以运行所有 Windows PowerShell 脚本。

如果你还有其他问题或需要进一步的帮助，请告诉我！（这个我也复制了嘿嘿(复制ChatGPT到markdown似乎有些费劲，生成的markdown过一些就不是了)）

<4>在Windows下任何命令中因为加sudo而产生问题

sudo : The term 'sudo' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling
of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ sudo hexo c
+ ~~~~
    + CategoryInfo          : ObjectNotFound: (sudo:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

如标题所示，删除sudo即可

<5> 没有使用专用密码在部署时出现错误

形如：

warning: in the working copy of 'archives/2024/08/index.html', LF will be replaced by CRLF the next time Git touches it
[main 9a7e12b] Site updated: 2024-08-20 18:22:33
 21 files changed, 1405 insertions(+), 384 deletions(-)
 rename {2022/05/25 => 2024/08/17}/hello-world/index.html (96%)
 create mode 100644 archives/2024/08/index.html
fatal: User cancelled dialog.

如标题所示，没有使用专用密码在部署时出现错误。您可以把这个好好看看：如何用GitHub和hexo搭建一个属于自己的博客? | Finder——## 6.创建专门“密码”方法