超详细Hexo+Github Pages搭建个人博客教程

四更一支花 發表於 2025-6-4 10:40:00

超详细Hexo+Github Pages搭建个人博客教程

<h2 id="一前置准备">一、前置准备</h2>
<ol>
<li>
首先准备一个 <code>github</code> 账号，没有就去注册一个
</li>
<li>
本次是基于 <code>git</code> 进行部署，所以首先安装一个 <code>git</code>，链接: https://git-scm.com/downloads
</li>
<li>
安装 <code>node.js</code> ，官网链接： Node.js — Download Node.js®
</li>
<li>
安装这两个，一般都会自动配置 <code>path</code>，配置这个目的是可以在任何路径下使用 <code>git 和 node.js</code>，如果没有配置环境变量，可以去配置一下。测试安装是否成功
</li>
</ol>
<pre><code># win + r 调出 cmd 命令行窗口，然后按照示例输入 # 如果出现版本号，说明已经安装成功了 C:\Users\xingzhu>node -v v18.16.1C:\Users\xingzhu>git --version git version 2.39.0.windows.2
</code></pre>
<ol start="5">
<li><code>git</code> 还需要配置相应的环境，实现 <code>git</code> 和 <code>github</code> 之间的交互，如使用 <code>git</code> 拉取 <code>github</code> 项目、配置相应的密钥等等，推荐一个配置学习的链接：使用git拉取github项目-CSDN博客</li>
</ol>
<h2 id="二搭建本地的博客-hexo-主题">二、搭建本地的博客 (Hexo 主题)</h2>
<ol>
<li>
新建一个文件夹用来存储博客，如我创建的 <code>MyBlog</code>，完整路径就是 <code>C:\MyBlog</code> ，建议路径中不要包含中文字符
</li>
<li>
创建完后，进入这个创建的文件夹，然后鼠标右击，点击 <code>Open Git Bash here</code>，进入一个命令行界面，然后输入 <code>npm install -g hexo-cli</code> ，将 Hexo 命令行工具安装到系统的全局环境中
</li>
</ol>
<pre><code>xingzhu@DESKTOP-34Q53IU MINGW64 /c/MyBlog $ npm install -g hexo-cli # 示例
</code></pre>
<ol start="3">
<li>待安装完毕，输入以下指令，将会新建一个 <code>myblogs</code> 文件夹，并且安装 Hexo 项目所需的依赖项</li>
</ol>
<pre><code># 创建一个新的 Hexo 项目
$ hexo init myblogs
$ cd myblogs
# 安装 Hexo 项目所需的依赖项
$ npm install
</code></pre>
执行完毕会生成这些文件
<img src="https://s2.loli.net/2025/03/06/q5nr786fMsymGJg.webp" alt="" loading="lazy">
<ol start="4">
<li>继续在 Git Bash 中执行指令 <code>hexo server</code></li>
</ol>
执行完毕后，打开本地浏览器，访问 <code>http://localhost:4000/</code>，出现以下界面，说明本地部署成功了
<img src="https://s2.loli.net/2025/03/06/PURNBYjmw8sO2yn.webp" alt="" loading="lazy">
<h2 id="三新建github仓库">三、新建Github仓库</h2>
<ol>
<li>
创建一个 github 仓库，点击 <code>Create repository</code>
</li>
<li>
需要特别注意的是仓库名字是 <code>Github用户名.github.io</code> 这个格式
</li>
</ol>
<img src="https://s2.loli.net/2025/03/06/Db3AN7iPTCus2LR.webp" alt="" loading="lazy">
<ol start="3">
<li>
注意记得勾选 <code>Add a README file</code>，为了方便后续查看 GitHub Pages 的域名和部署分支，然后点击创建
</li>
<li>
创建后，点击 <code>setting</code> 
<img src="https://s2.loli.net/2025/03/06/O1BSVnaFcHm3TWC.webp" alt="" loading="lazy">
</li>
<li>
查看这个分支，这里为 <code>main</code> 分支，后面写[配置文件]需要用到，然后 <code>https://xingzhuz.github.io</code> 就是后续我们访问的域名，目前也可以访问，只是只能显示出你的仓库名，即我的 <code>xingzhuz.github.io</code>
</li>
</ol>
<img src="https://s2.loli.net/2025/03/06/nGRCc9xMuTwPoQY.webp" alt="" loading="lazy">
<h2 id="四-将本地博客部署到-github-上">四、将本地博客部署到 Github 上</h2>
<ol>
<li>
打开博客目录，即我的 <code>C:\MyBlog\myblogs</code>，找到 <code>_config.yml</code> 文件，然后使用记事本或者其他软件打开，这里我用 <code>vscode</code> 打开
</li>
<li>
在末尾处加以下代码
</li>
</ol>
<pre><code># Deployment ## Docs: https://hexo.io/docs/one-command-deployment deploy: type: git repo: git@github.com:xingzhuz/xingzhuz.github.io.git branch: main
</code></pre>
这个代码是指，使用 <code>git</code> 方式部署，<code>repo</code> 的选择按照如下图片示例
<img src="https://s2.loli.net/2025/03/06/yrOmj94AnHGw2aW.webp" alt="" loading="lazy">
而那个 <code>branch</code> 填写的就是分支，就是上述第三步建仓库时候，<code>pages</code> 部分查看的分支，需要一致
上面这种图片是我已经部署上去了，所以后面会看到有文件，而没有部署之前，即你们现在的界面，就是空的，只有一个 <code>READMD.md</code> 文件
<ol start="3">
<li>在当前博客目录安装 git 插件，即 <code>C:\MyBlog\mybgs</code>，使用 <code>git bash</code> 执行这个命令</li>
</ol>
<pre><code>npm install hexo-deployer-git --save
</code></pre>
<ol start="4">
<li>最后依次执行</li>
</ol>
<pre><code># 清理 Hexo 缓存
hexo clean
# 重新生成静态文件
hexo generate
hexo deploy
</code></pre>
<img src="https://s2.loli.net/2025/03/06/AnYUpWb4y3ZRMfT.webp" alt="" loading="lazy">
如果设置了密钥，输入密钥即可，若最终出现 <code>Deploy done</code> 就说明部署成功了，此时就可以使用域名访问了，<code>https://用户名.github.io</code> ，如果界面没改变，等个一两分钟即可
<ol start="5">
<li>如果最后一步报错:</li>
</ol>
<pre><code>`Please make sure you have the correct access rights and the repository exists.FATAL Something's wrong. Maybe you can find the solution here:https://hexo.io/docs/troubleshooting.htmlError: Spawn failed at ChildProcess.<anonymous> (C:\MyBlog\myblogs\node_modules\hexo-deployer-git\node_modules\hexo-util\lib\spawn.js:51:21) at ChildProcess.emit (node:events:519:28) at cp.emit (C:\MyBlog\myblogs\node_modules\cross-spawn\lib\enoent.js:34:29) at ChildProcess._handle.onexit (node:internal/child_process:294:12)`
</code></pre>
<blockquote>
解决方案
</blockquote>
<ol>
<li>
首先检查上述配置过程中是否出错，即 <code>_config.yml</code> 文件是否出错
</li>
<li>
检查 <code>git</code> 是否能够连接 <code>github</code>
</li>
</ol>
<pre><code>git ls-remote https://github.com/xingzhuz/xingzhuz.github.io.git
</code></pre>
<ol start="3">
<li>如果不能连接，再测试 <code>SSH</code> 连接情况</li>
</ol>
<pre><code>`ssh -T git@github.com# 如果报错 ssh: connect to host github.com port 22: Connection timed out`

</code></pre>
<ul>
<li>
说明这个 SSH 连接超时，解决方案就是换个端口号
</li>
<li>
按照以下进行添加或者更改，更改电脑用户目录下的 <code>config</code> 文件，我的是 <code>C:\Users\xingzhu\.ssh\config</code>，以记事本打开或者其他方式打开
</li>
</ul>
<pre><code># 如果有这行数据，更改和添加对应的参数，如果没有，直接添加到末尾处 Host github.com Hostname ssh.github.com Port 443
</code></pre>
<ul>
<li>
更改后，注意需要刷新使其生效，有对应的命令，粗暴的方式就是重新启动即可
</li>
<li>
生效后，测试连接情况
</li>
</ul>
<pre><code>ssh -T git@github.com # 我的成功示例# Hi xingzhuz! You've successfully authenticated, but GitHub does not provide shell access.ping github.com # 显示一系列数字，即 IP# 如果都能成功，配置基本就可以了 # 此时再执行 hexo clean # 清理 Hexo 缓存： hexo generate # 重新生成静态文件 hexo deploy # hexo deploy
</code></pre>
<h2 id="五-基本使用">五、基本使用</h2>
<ol>
<li>
进入博客主目录，然后逐步进入 <code>source\_posts</code>，我的就是 <code>C:\MyBlog\myblogs\source\_posts</code>
</li>
<li>
然后新建一个 <code>命名.md</code> 文件，用记事本或者 Vscode 打开，如果有支持 markdown 格式的笔记软件的话，可以对应打开
</li>
</ol>
<img src="https://s2.loli.net/2025/03/06/K97cfswTDr85V1v.webp" alt="" loading="lazy">
<ol start="3">
<li>然后按照这样的格式，填写文章标题、发布日期、标签、种类、关键词等等，标题和时间是必需的，其余看自己需求，标签像我这样写就是同级标签</li>
</ol>
<img src="https://s2.loli.net/2025/03/06/EnfmZeR9uwV324Q.webp" alt="" loading="lazy">
<ol start="4">
<li>
这个使用 <code>---</code> 包括起来的内容称之为 <code>Front-matter</code>，即前置信息，用于给 Hexo 渲染该 md 文档，除了这三项，还有很多的配置项可以自己添加：
</li>
<li>
后面的内容就是文章实际的 markdown 语法了，按需写
</li>
<li>
也可以去搜索一些优秀的博主的框架，引进自己的博客中，按照博主的教程使用框架主题，按需设置
</li>
</ol>
<blockquote>
说明：参考： https://oceanwang.top/personal-website-7/
</blockquote> 
来源：https://www.cnblogs.com/xango/p/18909673

頁: [1]

琼殿技术论坛's Archiver

超详细Hexo+Github Pages搭建个人博客教程