用 Hexo + Github 搭建个人网站

Deyang Zeng
  2025-10-16 2025-10-16 Created   2026-03-26 17:09:51 2026-03-26 17:09:51 Updated      
  • 本文将指导你搭建你的第一个网站。
  • 示例系统：Windows 10 专业工作站版 22H2
  • 喜报：2025 年 10 月 15 日，Windows 10 终于失去了 Microsoft 的支持，完成了其成为一个优秀操作系统的最后一步。

环境配置

软件安装

  • 下载并安装 Node.js ，自带 npm (Node Package Manager) ：
    npm 下载页面
  • 下载并安装 Git ：

    回到桌面点击右键，点击 Open Git Bash Here。

    依次输入下列各行代码：
1
2
3
node --version
npm -v
git -v

如果均弹出版本号信息，则安装成功。

  • 安装 hexo，继续输入下列代码：
1
npm install hexo-cli -g

安装完成后输入代码校验：

1
hexo -v
  • 安装 WebStorm ：

    这是一个包含终端，设计、编辑网站，编辑、上传博客等功能的全能 IDE。之后对网站的所有操作都在这里进行。

文件夹初始化

在 D 盘或其他数据盘中新建文件夹，名称 hexo_blog （随意取名），未来所有的网站文件都会储存在这里。打开 hexo_blog 文件夹，文件夹空白处点击右键再次打开 Git Bash，输入代码对当前文件夹初始化：

1
hexo init

这个操作将会从 Github 拷贝文件，所以必要时可以连接 VPN。若成功初始化则提示：

1
INFO  Start blogging with Hexo!

会发现文件夹多出来很多内容：

  • public 最终所见网站的所有内容
  • node_modules 所有插件以及模块
  • _config.yml 站点配置文件，在这里更改网站主题
  • package.json 配置 hexo 运行所需 js 包
  • scaffolds 模板文件夹，包含对应模板内容
  • themes 主题文件，下载的主题在这里，hexo 官网提供 427 个主题
  • source 存放用户资源，博客正文、图片、头像等等

网站配置

本地网站

在 WebStorm 内打开 hexo_blog 文件夹，打开左下角的 Terminal（终端）

之后所有的终端命令都可以在这里执行，输入 hexo 命令：

1
hexo s

查看更多的 hexo 命令。 这里的hexo s是hexo server的简写，类似的也可以用hexo g代替hexo generate。

点击生成的网站，这就是一个简单的本地网站，默认是 hexo 内置主题 landscape ：

更换主题

如果不喜欢可以去 hexo 官网 下载其他主题。

例如我们这里选择第二个主题 Webstack，点击标题进入主题的 Github 页面，下拉找到 README，按照给出的命令回到 WebStorm 安装即可。

安装完主题后，在 WebStorm 左侧找到 themes 文件夹，展开可以看到下载好的主题，如果找不到则重新回去查看 Readme，看作者把他放哪去了：

之后安装运行以下命令：

1
2
npm install hexo-renderer-pug hexo-renderer-stylus --save
npm install hexo-deployer-git --save

打开 _config.yml 文件，这是站点配置文件，拉到最下面：

这里的 theme 项可以更改不同的主题：

1
theme : landscape

把 landscape 改为 webstack，下载新主题后还可能会有 _config. 主题名 .yml 文件，这是主题配置文件，主题配置文件的部分设置会覆盖站点配置文件。主题相当于框架，按照 Readme 这个指导书来改造主题变成你喜欢的样子。

建立图床

所谓图床，就是将博客中的所有的图片都存储到某个网络空间，这样他人在阅览博客时也会访问这些网络空间从而显示图片。这里用 Github + PicGO 建立图床。在 Github 建立一个公开仓库存放图片，用 PicGO 软件能够方便地将本地图片上传到 Github 并生成 Markdown 格式的图片链接。

Github

创建 Github 账户，点击头像，选择第三个选项 Repositories：

点击 New 新建仓库，仓库名字可以设为 blogimage，可见性选择 Public 公开，不然他人无法访问，添加 README，这会自动创建一个 Banch 分支：

然后点击 Create Repository。自动进入仓库的 Code 页面：

进入与 Code 平行的 Settings 页面，左侧菜单栏下滑到底，点击 Developer Settings 创建 Personal Access Tokens (Classic)，注意这里要勾选所有 repo 选项，其他的不勾选，点击 Generate token 后，记得额外保存 token ，因为这个页面关闭后将不再展示 token ，丢失 token 后只能删除仓库新建一个了。

PicGO

Token 用于 PicGO 的访问，官网下载 PicGO。

配置左侧的 Github 图床，仓库名填写Github 账号名 / 仓库名，分支一般是 main，Token 就是上文生成的，存储路径不必填写，自定义域名填写：

1
https://cdn.jsdelivr.net/gh/Github 账号名 / 仓库名

之后打开 PicGo 设置，确认 PicGo Server 的设置：

其他的设置就按自己喜好来。设置完后可以自己尝试上传一张图片测试，如果上传失败，可以打开 PicGo 设置 -> ** 设置日志文件 ** -> 点击打开，来查看日志

拉到最下面，会有报错代码，有比如 409，411，423 等等，Google 一下报错原因就很容易解决。

在线网站

Github 提供了 Github Pages 功能，可以免费建立 Github 网页，这里可以直接看官方教程：Quickstart for GitHub Pages 。
以及创建一个 SSH Key ，如果你之前并没有使用过 Git ：Generating a new SSH key and adding it to the ssh-agent。创建 SSH 密钥，会同时创建公钥和私钥，复制公钥放在 GitHub 上，本地储存私钥，期间会提示你创建私钥访问密码，不建议创建，因为创建后每次部署都要输一遍密码，直接不输入内容按两次 Enter 即可。依次执行下列命令：

1
2
3
4
ssh-keygen -t ed25519 -C "your_email@example.com"
cd ~/.ssh
cat id_ed25519.pub
ssh -T git@github.com

建立连接

网站编辑，创作博客等等操作都是在我们自己的电脑上进行的，要把这些改动上传到 Github ，然后 Github 生成在线网站，别人就可以访问了。我们再次在 Github 中建立一个新仓库用于管理我们上传过去的代码。然后打开 WebStorm 链接这个仓库， Git -> Manage Remotes：

第一次连接时可能不会出现 Git 选项，而是显示 VCS ，我们将这个项目 Share to Github 。最终来到这个这个页面：

点击左上角加号新建链接：

1
https://github.com/Github 用户名 / 随意取一个源码仓库名称 .git

WebStorm 会建立一个仓库，并将源码上传至仓库。总共有两个远程仓库，一个用于存放源码，一个用于存放静态网页，即 .io 的 Github Pages ，源码仓库在 WebStorm 设置，用于 Git 版本控制，网页仓库在 Hexo 配置页设置。打开 _config.yml ，拉到最下面配置部署：

分支都需要按照自己的实际情况来填写，默认是 main，也可能是 master 或者其他自定义分支，需要自己查看 Github 仓库的实际分支名称。这里部署的仓库的静态网页的仓库，我们每次更新源码或者添加新文章时，可以先 git push 源码仓库备份，然后再 hexo d 部署静态网页到静态网页仓库：

这里分别执行了三个命令

1
git add .

检测发生变动的源码文件，将变动暂存。

1
git commit -m " 说明 "

变动备注。

1
git push origin master

将变动推送到 origin 仓库的 master 分支。也可以直接用 Ctrl + K 在 Commit 区直接 push ，或者点击 Git -> 提交 -> 提交并推送。

网站上线

OK，网站部署已完成，在终端依次输入：

1
2
3
4
hexo clean
hexo g
hexo s
hexo d

本地预览后按 Ctrl + C 关闭。输入hexo d后若提示：

1
INFO  Deploy done: git

则部署完成，在浏览器网址处输入Github 账户名 .github.io，回车，就进入你自己的网站啦。不过由于 Github 在国内访问速度较慢，如果你想在国内有不错的访问体验则还需要另一番操作，租用国内的服务器、购买国内域名、ICP 备案等等，这就需要另找教程了。

上传博客

文本编辑

博客一般是用 Markdown 标记语言写的，你可以自己选择一款 Markdown Editor，比如笔者用的就是 VSCode ，下载后添加扩展 Markdown All in One:

然后用 VSCode 打开 source 文件夹，就能愉快地用 VSCode 编辑所有博客了。按住Ctrl + Shift + P就可以打开实时预览窗口。
此外，为了中文、英文联排的美观性，这里有一个自动加空格的项目：为什么我就是能这样娴熟地加上空格呢？

添加图片

我们上传图片用的 PicGo，PicGo 有一个从剪切板上传的选项，一般 Windows 截屏后，都会将截屏复制到剪切板，这里介绍一个比 Windows 截屏更好用的截屏工具： Snipaste 。能够方便地进行截屏、标注，配合 PicGo 直接形成了完美工作流，例如我将Alt + 1设置为 Snipaste 截屏，Ctrl + Shift + P 设置为 PicGo 剪切板上传，PicGo 上传后自动复制 Markdown 图片链接。

  • 所以我需要添加截屏图片时：
    • Alt + 1->Ctrl + Shift + P ->Ctrl + V
    • 选定区域截屏加标注-> 自动上传-> 插入的 Markdown 图片。
  • 如果需要上传本地图片，则选中图片：
    • Ctrl + C->Ctrl + Shift + P ->Ctrl + V

再次部署

编辑好新的.md文件后，在本地编译预览，确认没问题就可以重新部署，push 到 Github 上了，即便 Github 已经接受了新的改动，网站上的更新依旧会延迟几分钟。

一键发布

提交、推送、部署太麻烦，直接一个命令完成，打开 pakage.json 文件，修改 deploy 命令：

1
"deploy": "git add . && git commit -m \"文章更新\" && git push && hexo clean && hexo g && hexo d",

之后直接在终端输入：

1
npm run deploy

即可一键完成发布。

之后可以在桌面新建一个deploy.bat文件，右键 -> 编辑，填入：

1
2
3
4
5
6
7
8
@echo off
cd /d "C:项目地址"

echo Deploying...
call npm run deploy
echo.
echo Success!
pause > nul

之后改完文章，直接双击文件发布。

改 BUG

Github Pages Build 失败

写博客时遇到如下错误：

Git 推送正常，但是 Github Pages 出现 Build 失败：

在网上找到了解决方法，详见 https://github.com/orgs/community/discussions/106846

但尝试多次无果，之后重新创建文件夹 hexo init，链接到 .io 重新部署后可以正常 Build。猜测是由于多次本地文件搬运，导致某些核心组件缺失。

Nunjucks Error 解决办法

写博客时遇见如下错误：

Nunjucks Error 是一个常见错误。

  • 原因：Hexo 调用 Nunjucks 渲染文章，而文章中的{ something }会被 Nunjucks 识别为某种指令而报错
  • 解决办法：把被报错的内容用：
1
2
3
4
5
{% raw %}

{something}

{% endraw %}

包起来。

  • 注意：被包住的内容中，Markdown 标识符无法识别，例如标识无序编号的-会直接显示出来，并不产生小圆点，图片格式也会失效，如：

所以只要包住造成报错的公式内容即可：

同时这个方法还可以解决矩阵或多行公式渲染后挤成一行的问题，例如：

把矩阵包起来：

原因是换行符没有被正确识别，当然也可以用转义字符达成一样的效果。

所以，为了彻底杜绝这类渲染错误以及排版错误，建议再每次输入公式时都在前后分别加上 

1
{%raw%}

和 

1
{%endraw%}

Github 443 端口访问失败

报错...Failed to connect to github.com port 443...，参考 https://cloud.tencent.com/developer/article/2405656, 一般是使用 VPN 的情况下，获得代理端口号，配置：

1
2
3
git config --global http.proxy 127.0.0.1:<你的端口号>
git config --global https.proxy 127.0.0.1:<你的端口号>
git config --global -l

问题解决。

  • Title: 用 Hexo + Github 搭建个人网站
  • Author: Deyang Zeng
  • Created at : 2025-10-16 00:00:00
  • Updated at : 2026-03-26 17:09:51
  • Link: https://hexo.io/2025/10/16/2025-10-16-build-your-websites/
  • License: All Rights Reserved © Deyang Zeng
On this page
用 Hexo + Github 搭建个人网站
  1. 1. 环境配置
    1. 1.1. 软件安装
    2. 1.2. 文件夹初始化
  2. 2. 网站配置
    1. 2.1. 本地网站
    2. 2.2. 更换主题
    3. 2.3. 建立图床
    4. 2.4. 在线网站
    5. 2.5. 建立连接
  3. 3. 网站上线
  4. 4. 上传博客
    1. 4.1. 文本编辑
    2. 4.2. 添加图片
    3. 4.3. 再次部署
  5. 5. 一键发布
  6. 6. 改 BUG
    1. 6.1. Github Pages Build 失败
    2. 6.2. Nunjucks Error 解决办法
    3. 6.3. Github 443 端口访问失败