github.io博客教程-hexo-手动

教学如何从0开始搭建自己的github.io，本文章使用的是Hexo模板引擎，当然可以选择其他方式，包括不限于：自己手动创建，使用其他模板。

技术栈

git
hexo

前置准备

github账号
git
node.js
hexo（后文有安装教程）

正式教学

1. github建立项目

登录github账号，找到左上角的+号，New repository。
在repository name这里填入用户名.github.io（我的用户名是gulzxeric所以我填入gulzxeric.github.io）。再点最底下的创建，create repository。
页面上其他重要说明：
- Choose Visbility: 这个项目是公开的或是私密的？建立网站必须要确保是Public
- Add README：创立个带有项目名的README.md。自己随时可以创建，一般不勾选。

2. 测试网站成功与否

点击creating a new file
- 随便写点内容，html也好，纯文字也好（测试完即删，不要花费过多时间）。
- xxx in main, xxx必须填写index.html
- 最后，右上角提交。随后填写Commit message和Extend description（选填），记录的是这次修改的信息。
打开网址观察是否成功。
- 网站地址是用户名.github.io（我的是gulzxeric.github.io）
- 网站部署需要一段时间，大概是2-3分钟，可以在项目的Actions选项卡看部署状态。

Hexo

hexo简单介绍
- 什么是Hexo：Hexo 是一个快速、简洁且高效的博客框架。 Hexo 使用 Markdown（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。
- 网站链接：Hexo
- 安装：$ npm install -g hexo-cli（前置：已安装git和node.js）
Hexo的模板（主题）选择
- 介绍：这次选择Hexo的最主要的原因是Hexo有强大的社区，有很多开源模板供选择。github.io的个人博客页面，选择Hexo模板的不在少数（网络上的教学基本上也都是围绕着Hexo的）。
- 网站链接：Hexo模板
本次示范选用的模板是Ocean。

正式部署（模板自带的使用指南）

安装：打开终端，进入用来存放网页项目的文件夹（e.g. cd C:\Users\username\Desktop\blog01\web-try，我预计将文件存放到桌面的blog01/web-try文件夹内），输入 git clone https://github.com/zhwangart/hexo-theme-ocean.git themes/ocean，安装。
安装成功，你的文件夹内会出现themes文件夹

配置_config.yml文件：在当前文件夹（e.g. web-try）新建_config.yml,写入

title: gulzxeric's Blog # 换成自己的blog的名字
author: gulzxeric # 换成自己的名字
language: zh-CN
timezone: 'Asia/Shanghai'
url: https://gulzxeric.github.io # 换成自己的 https://用户名.github.io
theme: ocean
deploy:
   type: git
   repo: https://github.com/gulzxeric/gulzxeric.github.io.git # 换成自己的 https://github.com/用户名/用户名.github.io.git
   branch: main

配置package.json文件：在当前文件夹（e.g. web-try）新建package.json写入一下文字，并在终端输入npm install，运行

{
"name": "blog",
"version": "1.0.0",
"description": "",
"main": "index.js",
"directories": {
   "doc": "docs"
},
"scripts": {
   "server": "hexo server",
   "generate": "hexo generate",
   "deploy": "hexo deploy",
   "clean": "hexo clean",
   "test": "echo \"Error: no test specified\" && exit 1"
},
"hexo": {
   "version": "8.1.2"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs",
"dependencies": {
   "hexo": "^8.1.2",
   "hexo-cli": "^4.3.2",
   "hexo-deployer-git": "^4.0.0",
   "hexo-generator-archive": "^2.0.0",
   "hexo-generator-category": "^2.0.0",
   "hexo-generator-index": "^4.0.0",
   "hexo-generator-searchdb": "^1.5.0",
   "hexo-generator-tag": "^2.0.0",
   "hexo-renderer-ejs": "^2.0.0",
   "hexo-renderer-marked": "^7.0.1",
   "hexo-renderer-stylus": "^3.0.1",
   "hexo-server": "^3.0.0",
   "hexo-theme-redefine": "^2.9.0",
   "hexo-wordcount": "^6.0.1"
   }
}

解决兼容问题：给以下 6 个文件的开头各加 3 行 front-matter(themes/ocean/layout/index.ejs，themes/ocean/layout/，post.ejs

，themes/ocean/layout/page.ejs
，themes/ocean/layout/archive.ejs
，themes/ocean/layout/tags.ejs
，themes/ocean/layout/categories.ejs（layout.ejs 本身不加）)：

1
2
3

---
layout: layout
---

6. 最后，，在终端输入hexo new 测试文章，自动添加文件夹source\_posts，并生成”测试文章.md”的空白文章（包括必要信息，文章正文空白）。

部署github

在终端输入指令hexo d，根据_config.yml里面的相关配置，自动部署到github。等待一段时间的部署（2-3分钟），打开你的网站用户名.github.io就可以看到网站部署成功。

新建文章以及更新页面

新建文章，在终端输入hexo new 文章名，文章名.md就会出现在source/_posts/文件夹内，打开编辑即可。
推送更新的文章，只要修改了任何配置，想要网站同步更新，终端输入hexo g -d，就会更新到github，等待一小段事件后网站同步更新。

写在最后

除了这些内容外，关于开放评论系统，写加密文章等等内容，都可以在Hexo官网或者模板的介绍界面找到相关配置。这里就不做过多介绍。

如今，在新建仓库之后，之后任务可以全部AI执行。工作流可以是跟Agent说：推荐hexo模板 -> 下载到本地 -> 修改相关配置 -> 部署到https://用户名.github.io。之后想要开放评论系统之类的，也都可以用Agent完成。此文章仅供参考，旨在帮助大家理清 Hexo 部署的底层逻辑。 因为只有亲自踩过手动配置的坑，理解了 _config.yml、package.json 以及 Front-matter 的协作机制，在 AI 偶尔“幻觉”或配置冲突时，你才能一眼看清本质，并给出最精准的 Prompt 去纠正它。

技术在变，但折腾精神不变。希望这篇教程能帮你成功迈出搭建个人博客的第一步。