本文是 Hexo 博客系列的第二篇，介绍如何将博客部署至 GitLab Pages，并通过自定义脚本实现快捷运行与版本同步。

🌐 什么是GitLab Pages？

GitLab Pages 简介
GitLab Pages 是 GitLab 提供的静态网站托管服务。通过将网站文件推送到 GitLab 仓库，GitLab 会自动构建并部署网站，用户可以通过 GitLab 提供的域名访问自己的网站。

📝 仓库命名规则

重要提醒
假设你的用户名是 crowforkotlin，那么仓库名称必须是 crowforkotlin.gitlab.io
这个命名规则是固定的，不能随意更改！

⚙️ 配置站点URL

在推送代码到GitLab之前，需要修改根目录的 _config.yml 文件：

# Set your site url here
url: https://crowforkotlin.gitlab.io/

🏃‍♂️ 什么是GitLab Runner？

GitLab Runner 介绍
GitLab Runner 是一个开源项目，用于 GitLab CI/CD 的执行环境。它可以在多种环境中运行，包括本地机器、虚拟机和云实例。GitLab Runner 负责接收来自 GitLab 的构建请求，并在指定的环境中执行相应的构建任务。

📄 配置CI/CD文件

当你把代码推送到GitLab后，此时GitLab Pages并不会生效，因为还需要一个 .gitlab-ci.yml 文件。这个文件是GitLab Runner的配置文件，GitLab Runner会根据这个文件来执行相应的脚本。

创建配置文件
在项目根目录创建 .gitlab-ci.yml 文件

CI/CD 配置示例

image: node:16.16.0  # 选用 Node.js 16.16.0 版本

cache:
  paths:
    - node_modules/

before_script:
  - npm install hexo-cli
  - npm install

pages:
  tags:
    - Home # 自定义标签，后续会用到
  script:
    - hexo clean 
    - hexo generate
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

🔧 安装和配置GitLab Runner

为什么选择本地Runner？
使用本地GitLab Runner可以：

  • 省去云端成本开销
  • 减少云端启动容器时间
  • 更好的控制构建环境
  • 避免公共Runner的排队等待

步骤1: 下载GitLab Runner

GitLab Runner 官方下载 Windows 注册指南

步骤2: 注册Runner

  1. 打开你的GitLab Pages仓库
  2. 进入 Settings → CI/CD → Runners
  3. 点击 Create project runner
  4. 输入你在 .gitlab-ci.yml 中设置的tags（如：Home）
  5. 点击 Create Runner

复制页面显示的注册命令到命令行执行：

gitlab-runner register --url https://gitlab.com --token glrt-xxxxxxxxxx

由于Windows下可能双击无反应，需要使用Git Bash、CMD或PowerShell等命令行工具执行

步骤3: 配置Runner

找到配置文件 C:\Program Files\Git\config.toml，可能需要手动修改shell为powershell：

[[runners]]
  name = "Home"
  url = "https://gitlab.com"
  pre_clone_script = "git config --global --add safe.directory ${CI_PROJECT_DIR}"
  id = 47770241
  token = "glrt-xxxxxxxxxx"
  token_obtained_at = 2025-06-10T07:33:07Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "shell"
  shell = "powershell"  # 重要：设置为powershell
  [runners.cache]
    MaxUploadedArchiveSize = 0

步骤4: 启动Runner

# 停止服务
gitlab-runner stop

# 启动服务  
gitlab-runner start

🚀 部署流程

  1. 推送代码到GitLab
  2. 启动本地Runner服务
  3. 查看构建过程
  4. 访问你的网站：https://your-username.gitlab.io/

🎉 部署成功！
现在你可以通过GitLab提供的域名访问你的博客了

🛠️ 自动化脚本集合

提升效率
每次手动执行一大串流程确实繁琐，我编写了一套自动化脚本来快速完成日常操作。

📦 脚本下载

获取完整脚本

🔧 使用方法

  1. 克隆脚本仓库

    git clone https://gitlab.com/crowforkotlin/page-storage-hexo-script.git

  2. 修改脚本配置

    • 编辑脚本中的 BLOG_PATH 变量
    • 根据你的项目路径进行调整

  3. 配置环境变量

    • 将脚本目录添加到系统 PATH
    • 或者直接在脚本目录下使用

  4. 运行环境

    • Git Bash（推荐）
    • CMD
    • PowerShell

在每个脚本中找到并修改以下路径：

# 修改为你的博客项目路径
BLOG_PATH="/d/fish/your-username.gitlab.io"

常见路径格式：

  • Windows: /d/fish/crowforkotlin.gitlab.io
  • Linux/Mac: /home/user/crowforkotlin.gitlab.io

注意：路径中不要包含中文字符，建议使用英文路径

Linux/Mac 用户：

# 给脚本添加执行权限
chmod +x *.sh

Windows 用户：

  • 确保已安装 Git Bash
  • 可能需要以管理员身份运行某些脚本
  • 部分脚本会自动请求管理员权限

功能：自动检测权限并启动GitLab Runner服务

#!/bin/bash

# 检查管理员权限
net session > /dev/null 2>&1

if [ $? -eq 0 ]; then
  # 已经是管理员
  echo "Running with administrator privileges..."
  echo "Restarting GitLab Runner service..."
  
  gitlab-runner stop
  gitlab-runner start
  
  echo ""
  echo "Service restart command issued."
  
else
  # 需要提权
  echo "Administrator privileges required. Attempting to re-launch with elevation..."
  
  # 使用PowerShell提权重新运行
  powershell.exe -Command "Start-Process -FilePath 'bash' -ArgumentList '-c \"$(readlink -f "$0")\"' -Verb RunAs"
fi

功能：一键提交并推送代码到GitLab仓库

#!/bin/bash

# 定义博客项目路径
BLOG_PATH="/d/fish/crowforkotlin.gitlab.io"

echo "==================================="
echo "push blog to git"
echo "==================================="
echo "Working directory: $BLOG_PATH"
echo ""

# 切换到博客项目目录
cd "$BLOG_PATH"

git add -A
git commit -m ":label: update"
git push origin main -f

功能：清理、生成并启动本地预览服务器

#!/bin/bash

# 定义博客项目路径
BLOG_PATH="/d/fish/crowforkotlin.gitlab.io"

echo "==================================="
echo " Hexo Blog Workflow Started"
echo "==================================="
echo "Working directory: $BLOG_PATH"
echo ""

# 切换到博客项目目录
cd "$BLOG_PATH"

echo "[1/3] Cleaning old files..."
hexo clean

echo ""
echo "[2/3] Generating new static files..."
hexo g -f

echo ""
echo "[3/3] Starting local server for preview..."
hexo server

echo ""
echo "==================================="
echo " All tasks completed."
echo " Local server is running at http://localhost:4000"
echo "==================================="

# 让窗口保持打开
read -p "Press Enter to exit..."

功能：组合脚本，一键完成启动Runner和推送代码

#!/bin/bash

echo "🚀 Starting automated deployment..."

# 启动GitLab Runner
./gitlab-start.sh

echo ""
echo "⏳ Waiting for runner to start..."
sleep 3

# 推送代码到GitLab
./gitlab-update.sh

echo ""
echo "✅ Deployment process completed!"
echo "🌐 Check your GitLab Pages site for updates"

📚 参考资源

自动化脚本仓库 Runner注册指南 GitLab Pages文档

🎯 快捷方式配置与使用

极简操作
通过快捷脚本，参考我已经开源的script仓库，只需要输入 launch 即可自动推送并运行runner，当然你也可以根据需求自定义脚本功能。

🚀 一键部署 - launch 命令

使用开源的脚本仓库，你可以实现：

  • 一键启动：自动运行GitLab Runner
  • 自动推送：提交并推送代码到GitLab

方法一：Windows快捷方式

在创建快捷方式时，输入对象的位置：

"C:\Program Files\Git\git-bash.exe" -c "launch"

配置步骤：

  1. 右键桌面 → 新建 → 快捷方式
  2. 输入上述命令路径
  3. 命名为 “Hexo Deploy” 或其他你喜欢的名称
  4. 完成创建

提醒：需要先将脚本目录添加到系统环境变量PATH中

方法二：uTools工具（推荐）

为什么选择uTools？

  • 全局快速启动
  • 无需记忆复杂路径
  • 支持关键词搜索
  • 界面美观易用

配置步骤：

  1. 下载并安装 uTools
  2. 打开uTools设置
  3. 进入 设置 → 文件启动选项
  4. 将launch脚本快捷方式拖入启动选项
  5. 设置关键词（如：launch、hexo、deploy）

使用方法：

  • 按下 Alt + Space 唤起uTools
  • 输入 launch 或设置的关键词
  • 回车执行，完成一键部署

效果：更新整个Hexo博客并推送更新到GitLab Pages，只需要输入一个关键词！

方法三：自定义launch脚本

你可以根据需求修改launch脚本的功能：

#!/bin/bash
# launch.sh - 自定义一键部署脚本

echo "🚀 Starting Hexo deployment workflow..."

# 可选：添加预处理步骤
echo "📝 Checking for new posts..."

# 启动GitLab Runner
echo "🔧 Starting GitLab Runner..."
./gitlab-start.sh

# 等待Runner启动
echo "⏳ Waiting for runner to initialize..."
sleep 5

# 推送代码
echo "📤 Pushing to GitLab..."
./gitlab-update.sh

# 可选：打开浏览器预览
# echo "🌐 Opening browser preview..."
# start https://your-username.gitlab.io

echo "✅ Deployment completed successfully!"
echo "🎉 Your blog is now updated!"

# 保持窗口打开以查看结果
read -p "Press Enter to exit..."

自定义选项：

  • 添加构建前检查
  • 集成图片压缩
  • 自动打开浏览器预览
  • 发送部署完成通知

🛠️ 环境变量配置

环境变量设置
为了在任意位置使用脚本命令，需要配置系统环境变量

Windows 配置步骤：

  1. 右键 “此电脑” → 属性
  2. 高级系统设置 → 环境变量
  3. 在系统变量中找到 “Path”
  4. 添加脚本所在目录路径
  5. 确定保存

验证配置：

# 在任意目录打开命令行，输入：
launch
# 如果能正常执行，说明配置成功

📋 常用命令速查

启动Runner 停止Runner 推送代码 本地预览
完整命令列表
# GitLab Runner 管理
gitlab-runner start    # 启动服务
gitlab-runner stop     # 停止服务
gitlab-runner status   # 查看状态

# Git 操作
git add -A                    # 添加所有文件
git commit -m "message"       # 提交变更
git push origin main -f       # 强制推送到主分支

# Hexo 操作
hexo clean      # 清理缓存
hexo generate   # 生成静态文件
hexo server     # 启动本地服务器
hexo deploy     # 部署到远程

💡 故障排除

常见问题解决方案

问题现象：Runner服务无法正常启动

解决方案：

  1. 检查管理员权限
  2. 确认Runner已正确注册
  3. 检查配置文件路径
  4. 重新安装Runner服务
# 重新安装服务
gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

问题现象：CI/CD流水线构建失败

解决方案：

  1. 检查 .gitlab-ci.yml 语法
  2. 确认Node.js版本兼容性
  3. 检查依赖包安装
  4. 查看详细构建日志
# 本地测试构建过程
hexo clean
hexo generate

问题现象：脚本无法执行或权限不足

解决方案：

  1. 以管理员身份运行
  2. 修改脚本执行权限
  3. 检查路径配置
  4. 确认Git Bash环境
# Linux/Mac 添加执行权限
chmod +x script-name.sh

🎉 部署成功检查

部署完成后的验证步骤

  1. ✅ GitLab Pages构建成功
  2. ✅ 网站可正常访问
  3. ✅ 样式和资源加载正常
  4. ✅ 文章内容显示正确

进阶小贴士

  • 脚本路径需要根据实际情况修改
  • 建议将常用脚本添加到系统环境变量中
  • 可以根据需求自定义脚本功能
  • 记得定期检查GitLab Runner的运行状态
  • 建议定期备份重要的配置文件
  • 可以设置定时任务自动执行部署脚本