Ubuntu 本地搭建 Jekyll 博客教程

在 Ubuntu 上部署 Jekyll 博客，可以方便地写作、预览和发布到 GitHub Pages。

---

GitHub 设置

一、准备工作

打开 https://github.com/ 注册账号。 找到自己的用户名，GitHub Pages 的地址规则是： [https://你的用户名.github.io]

二、创建博客仓库

1. 打开 Minimal Mistakes 官方 Remote Theme Starter 模板：
   https://github.com/mmistakes/mm-github-pages-starter/generate

2. 在 Repository name 填：qiyu-lu.github.io

3. 点击 Create repository。

三、开启 GitHub Pages

1. 进入仓库 Settings → Pages。
2. Branch 选择 master（我的仓库是 master 分支）。
3. Folder 选择 / (root)。
4. 点击保存，等待 1～5 分钟，访问：https://qiyu-lu.github.io

四、修改博客信息

打开仓库里的 _config.yml 文件，修改如下内容：

title: 我的个人博客
author:
name: Qiyu
bio: 分享学习与生活
minimal_mistakes_skin: dark

保存后刷新网页即可看到变化。

五、写第一篇文章

在仓库的 _posts 文件夹下，新建文件：

2025-08-09-my-first-post.md

内容示例：

---
title: 我的第一篇博客
date: 2025-08-09
categories: [随笔]
tags: [生活]
---

这里写文章内容。

---

本地部署

一、安装 Ruby（使用 rbenv）

Ubuntu 系统自带 Ruby 版本较旧，直接使用会导致 Jekyll 无法安装。推荐用 rbenv + ruby-build 来安装最新 Ruby。

# 更新系统
sudo apt update

# 安装 rbenv 与依赖
sudo apt install -y rbenv git build-essential zlib1g-dev

# 配置 rbenv 环境变量
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

# 安装 ruby-build 插件
mkdir -p ~/.rbenv/plugins
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

# 安装 Ruby（推荐 3.2.2）
rbenv install 3.2.2
rbenv global 3.2.2

# 确认版本
ruby -v

---

二、配置 gem 镜像源（加速）

gem sources --remove https://rubygems.org/
gem sources -a https://mirrors.tuna.tsinghua.edu.cn/rubygems/
gem sources -l   # 确认只剩清华源

---

三、安装 Jekyll 和 Bundler

gem install bundler jekyll

---

四、克隆博客仓库并安装依赖

# 建立目录并进入
mkdir ~/Jekyll_blog && cd ~/Jekyll_blog

# 克隆博客仓库（换成你自己的用户名）
git clone https://github.com/你的用户名/你的用户名.github.io.git

# 进入博客目录
cd 你的用户名.github.io

# 安装依赖
bundle install

---

五、本地运行博客

bundle exec jekyll serve

访问 http://localhost:4000 查看效果。

• 如果端口被占用，可改用：

bundle exec jekyll serve --port 4001

然后访问 http://localhost:4001。

• 自动刷新网页：

bundle exec jekyll serve --livereload

• 在执行这句语句时，会遇到打不开网页的情况，我这里是由于网络原因，主题无法下载
• 我选择下载主题到本地，在_config文件中替换主题，注释掉之前的，使用下载的theme: minimal-mistakes-jekyll

  gem install minimal-mistakes-jekyll
  # 然后在你项目根目录找到 Gemfile，添加：
  gem "minimal-mistakes-jekyll"
  bundle install  # 在项目根目录执行
  

• 然后再执行 bundle exec jekyll serve --livereload ，能够在终端正常输出 LiveReload address Server address Server running… press ctrl-c to stop. LiveReload: Browser connected 此时网页也可以打开

• 然后这里主题使用的本地配置，我想着不push这个_config 文件，而只push修改的md博客文件

  方法一

  git update-index --assume-unchanged _config.yml
  # Git 会忽略本地 _config.yml 的修改，不会在 git status 中显示为已修改，也不会 push。
  

  如果以后想恢复跟踪: git update-index --no-assume-unchanged _config.yml

  方法二

• 手动选择 push 可以在 push 时只 push _posts/：

  git add _posts/
  git commit -m "Update blog posts"
  git push origin master
  #git push origin <本地分支>:<远程分支> # 本地分支通过 git branch 命令查询， 远程分支通过 git remote show origin查询
  

  这样即使 _config.yml 本地修改了，也不会被 push。

• 建议不要修改_config.yaml，使用一个稳定的网络最方便

六 修改代码样式

• 确认你有 assets/css/main.scss，在你的 Jekyll 项目里应该已经有：

    your_blog/
    ├─ _config.yml
    ├─ assets/
    │   └─ css/
    │       └─ main.scss   ✅ 主题入口文件
    ├─ _posts/
    ├─ _pages/
    └─ ...
  
  

  如果 assets/css/main.scss 不存在，就自己新建。

• 编辑 assets/css/main.scss，在文件开头写上 Jekyll 的 Sass 头信息，然后引入主题和自定义样式：

    ---
    # Only the main Sass file needs front matter (the dashes are enough)
    ---
  
    @import "minimal-mistakes/skins/mint"; // 你现在用的皮肤（mint），可以换成 default, dark 等
    @import "minimal-mistakes";            // 引入主题
    @import "custom/custom";               // ✅ 引入自定义样式（下一步要新建）
  
  

  注意：前两行 — 必须有，否则 Jekyll 不会编译这个文件。

• 新建 _sass/custom/custom.scss,在项目里新建目录 _sass/custom/，然后建文件 custom.scss，写上你自己的样式。例如美化行内代码：

    // 行内代码样式
    code {
    background: #fff2cc;   // 柔和背景色
    padding: 2px 4px;
    border-radius: 4px;
    font-weight: 600;      // 半粗
    color: #c7254e;        // 深红色字体
    }
  
    // 代码块样式（可选）
    pre {
    background: #2d2d2d;   // 深色背景
    color: #f8f8f2;        // 浅色字体
    padding: 1rem;
    border-radius: 8px;
    overflow-x: auto;
    }
  
  

七、写作与发布流程

1. 写文章

   • 在 _posts/ 目录下新建文件：

       YYYY-MM-DD-title.md
     

   • 使用你喜欢的编辑器（VSCode、Typora、Vim、Gedit 等）。

2. 本地预览

    bundle exec jekyll serve
   

   • 如果你加了 –livereload，修改保存后页面会自动刷新，非常方便。

   浏览器打开 http://localhost:4000。

3. 提交修改并推送到 GitHub

    git add .
    git commit -m "更新博客内容"
    git push
   

   • 如果 commit 遇到错误：

    git config --global user.name "qiyu-lu"
    git config --global user.email "your_email@example.com"
   

   • 如果 push 遇到 403 权限错误，推荐使用 GitHub Personal Access Token 或 SSH 密钥：

   使用 Token：

   • 登录 GitHub → 右上角头像 → Settings
   • 左侧栏 → Developer settings → Personal access tokens → Tokens (classic)
   • 点击 Generate new token
   • 勾选 repo 权限（保证能推送代码）
   • 保存生成的 token（只显示一次！）

    git remote set-url origin https://<YOUR_TOKEN>@github.com/qiyu-lu/qiyu-lu.github.io.git
    git push
   

   使用 SSH：

    ssh-keygen -t ed25519 -C "your_email@example.com"
    # 一路回车，生成 ~/.ssh/id_ed25519.pub。
    # 复制 ~/.ssh/id_ed25519.pub 到 GitHub → Settings → SSH and GPG keys → New SSH key
    git remote set-url origin git@github.com:qiyu-lu/qiyu-lu.github.io.git
    git push
   

GitHub Pages 会自动更新你的网站。

---

吧、最常用命令速查表

写博客日常只需记住三步：

# 1. 进入博客目录
cd ~/Jekyll_blog/你的用户名.github.io

# 2. 本地预览
bundle exec jekyll serve

# 3. 提交到 GitHub
git add .
git commit -m "更新博客内容"
git push

---