技术博客搭建：GitHub Pages + Hexo/Jekyll

FreeGuideOnline 最新 2026-07-02

bash git config --global user.name "你的用户名" git config --global user.email "你的邮箱"


### 3. 安装生成器所需运行环境

#### 选择 Hexo：安装 Node.js

前往 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本并安装。安装完成后验证：

```bash
node -v
npm -v

选择 Jekyll：安装 Ruby 及开发工具

Windows：安装 RubyInstaller（带 Devkit 的版本），运行安装程序，最后一步勾选 MSYS2 开发工具链。
macOS：系统自带 Ruby，执行 gem update --system；也可用 Homebrew 安装新版。
Linux：sudo apt install ruby-full build-essential zlib1g-dev

避免 root 安装 gems，配置 gem 用户目录（可选）：

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

安装 Jekyll 和 Bundler：

gem install jekyll bundler

Hexo 方案：从初始化到部署

1. 安装 Hexo 脚手架工具

npm install -g hexo-cli

2. 初始化博客项目

在本地选择一个文件夹（例如 ~/Projects），执行：

hexo init myblog
cd myblog
npm install

此时目录结构如下：

_config.yml：站点配置文件
source/_posts/：存放 Markdown 文章
themes/：主题目录
scaffolds/：文章模板

3. 本地预览

hexo server

浏览器打开 http://localhost:4000，看到默认的 Hello World 页面即成功。

4. 配置站点信息

用编辑器打开 _config.yml，修改关键字段：

title: 我的技术博客
subtitle: 'stay hungry, stay foolish'
description: '专注于后端、架构与云原生'
author: 你的名字
language: zh-CN
timezone: 'Asia/Shanghai'
url: https://你的用户名.github.io

更多配置如主题、部署等后面会逐步添加。

5. 安装并配置主题（以 Next 为例）

安装最新主题：

git clone https://github.com/next-theme/hexo-theme-next themes/next

修改 _config.yml 中 theme 字段为 next：

theme: next

然后根据需要调整 Next 主题的 _config.next.yml（从 node_modules/hexo-theme-next/_config.yml 复制一份到站点根目录）。

6. 部署到 GitHub Pages

安装部署插件：

npm install hexo-deployer-git --save

在 _config.yml 末尾添加部署配置：

deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: master  # 或 main, 根据你的默认分支

如果你使用的是其他仓库名，repo 填写完整地址，branch 推荐使用 gh-pages 分支（参见下一节分支部署）。

执行一条命令完成生成并上传：

hexo clean && hexo deploy

完成后访问 https://你的用户名.github.io，博客已上线。

7. 写作与发布流程

新建文章：

hexo new "我的第一篇技术文章"

这会在 source/_posts/ 下创建一个 Markdown 文件。编辑完内容后，本地预览：

hexo server

发布三部曲：

hexo clean
hexo generate
hexo deploy

或简写 hexo g -d。

8. 自定义域名（可选）

在 source 目录下创建 CNAME 文件，内容为你的域名（如 blog.yourdomain.com）。部署后，去域名 DNS 服务商添加 CNAME 记录指向 你的用户名.github.io。等待解析生效即可。

Jekyll 方案：从初始化到部署

1. 创建新的 Jekyll 站点

jekyll new myblog
cd myblog

目录结构：

_config.yml：站点配置
_posts/：文章目录
_layouts/, _includes/：模板系统
index.md：首页

2. 本地预览

bundle exec jekyll serve

访问 http://127.0.0.1:4000 查看网站。

3. 配置基本信息

编辑 _config.yml：

title: 我的技术博客
description: 记录学习与成长
baseurl: "" # 如果仓库是 username.github.io 则留空
url: "https://你的用户名.github.io"
author: 你的名字

4. 选择主题

Jekyll 默认支持 minima 主题，你可以在 Jekyll Themes 挑选其他主题。安装方法通常是替换 Gemfile 中的主题 gem，并更新 _config.yml 的 theme 字段。

5. 把网站托管到 GitHub Pages

在 GitHub 上创建 你的用户名.github.io 仓库（或普通仓库）。将本地项目初始化为 Git 仓库并关联远程：

git init
git add .
git commit -m "初始化博客"
git remote add origin https://github.com/你的用户名/你的用户名.github.io.git
git push -u origin main  # 或 master

方法一：直接推送源码
如果你的仓库名叫 username.github.io，GitHub Pages 会默认将 main 分支下的站点根目录作为发布来源。推送后稍等片刻即可在 https://username.github.io 访问。

如果你的仓库叫其他名字，需要在仓库 Settings > Pages 中将 Source 设置为 main 分支，访问地址为 https://username.github.io/仓库名。

方法二：使用 GitHub Actions 自动构建（推荐）
可以推送源码到仓库，由 GitHub Actions 自动构建后部署到 gh-pages 分支。创建一个 .github/workflows/jekyll.yml 文件：

name: Deploy Jekyll site

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      - name: Build site
        run: bundle exec jekyll build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

然后在 Settings > Pages 中将 Source 设为 gh-pages 分支根目录。推送后 Action 会自动完成构建部署。

6. 写作流程

新建文章，文件名遵循 YYYY-MM-DD-标题.md 格式，存放在 _posts/ 目录。文章前需要加上 front matter：

---
layout: post
title: "我的第一篇技术文章"
date: 2025-03-15 12:00:00 +0800
categories: technology
---