1. 为什么选择Gitee Pages + Hexo组合
最近两年,我帮不少朋友搭建过个人技术博客,试过各种方案后,发现Gitee Pages + Hexo这个组合特别适合国内开发者。先说Gitee Pages,它最大的优势就是国内访问速度快,不像某些国外服务经常出现加载缓慢的情况。而且完全免费,不需要自己买服务器,对于刚入门的技术爱好者特别友好。
Hexo作为静态博客生成器,我用过不下十次,最直观的感受就是简单高效。它基于Node.js,用Markdown写文章特别顺手,生成静态页面的速度比Jekyll快很多。去年我给团队做内部文档系统时,实测Hexo生成1000篇文章只需要不到3秒,这个性能完全能满足个人博客的需求。
这个组合的另一个优势是学习成本低。你不需要掌握复杂的前端框架,只要会基本的Git操作和Markdown语法就能上手。我带的实习生基本上半天就能学会整套流程,第二天就能产出自己的技术文章。下面这张表格对比了几种常见方案:
| 方案 | 访问速度 | 搭建难度 | 维护成本 | 定制灵活性 |
|---|---|---|---|---|
| Gitee+Hexo | ★★★★★ | ★★☆☆☆ | ★☆☆☆☆ | ★★★☆☆ |
| GitHub+Jekyll | ★★☆☆☆ | ★★★☆☆ | ★★☆☆☆ | ★★★★☆ |
| 自建WordPress | ★★★☆☆ | ★★★★☆ | ★★★★☆ | ★★★★★ |
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从零开始的环境准备
2.1 安装Node.js和Git
Hexo基于Node.js,所以第一步要安装Node.js环境。我推荐直接去Node.js官网下载LTS版本,目前最新的是18.x。安装过程很简单,一路点击下一步就行,但有个细节要注意:记得勾选"Add to PATH"选项,这样后面在命令行直接使用npm命令。
安装完成后,打开终端(Windows用CMD或PowerShell,Mac用Terminal),输入以下命令验证是否安装成功:
bash复制node -v
npm -v
如果看到版本号输出(比如v18.12.1),说明安装正确。我遇到过不少新手卡在这一步,通常都是因为没勾选PATH选项导致命令找不到,这时需要手动添加环境变量。
Git的安装同样简单,从Git官网下载安装包。安装时有个关键选择:换行符处理。建议选择"Checkout as-is, commit Unix-style line endings",这样可以避免Windows和Unix系统之间的换行符问题。
2.2 配置国内镜像源
npm默认源在国外,下载速度很慢。我强烈建议换成国内镜像源,实测能提升10倍以上的下载速度:
bash复制npm config set registry https://registry.npmmirror.com
这个命令会修改~/.npmrc文件。为了验证是否生效,可以运行:
bash复制npm config get registry
如果返回的是npmmirror.com的地址,说明配置成功。去年我在公司内网搭建环境时,发现有些企业网络会拦截npm请求,这时还需要配置代理,但个人用户一般不需要考虑这个问题。
3. Hexo博客初始化
3.1 安装Hexo并创建项目
环境准备好后,用npm全局安装Hexo命令行工具:
bash复制npm install -g hexo-cli
安装完成后,找个合适的目录创建博客项目。我习惯在~/Documents下建个blog文件夹:
bash复制hexo init myblog
cd myblog
npm install
这个命令会生成一个标准的Hexo项目结构,主要目录说明如下:
source/_posts:存放Markdown格式的博客文章themes:存放主题文件public:生成的静态文件(执行hexo generate后出现)_config.yml:全局配置文件
3.2 本地运行和基础配置
输入以下命令启动本地服务器:
bash复制hexo server
默认会在http://localhost:4000 启动服务。第一次运行时,你可能会看到端口冲突的错误。这时可以指定其他端口:
bash复制hexo server -p 5000
打开_config.yml文件,有几个关键配置需要修改:
yaml复制title: 你的博客标题
subtitle: 副标题
description: 博客描述
author: 你的名字
language: zh-CN # 中文支持
timezone: Asia/Shanghai
改完后记得重启服务才能生效。我建议在初期多尝试修改这些配置,熟悉Hexo的配置方式。有个小技巧:每次修改配置后,可以用hexo clean清理缓存,避免一些奇怪的缓存问题。
4. Gitee Pages部署实战
4.1 创建Gitee仓库
首先在Gitee上新建一个仓库,注意仓库名有特殊要求:
- 个人主页:必须用
用户名.gitee.io - 项目主页:任意名称,但需要在设置中开启Pages服务
我建议直接用用户名.gitee.io这种形式,这样访问地址最简洁。创建仓库时,记得勾选"使用Readme文件初始化仓库",这样可以避免空仓库的一些问题。
4.2 配置Hexo部署插件
回到本地项目,安装Hexo的Git部署插件:
bash复制npm install hexo-deployer-git --save
然后修改_config.yml,添加部署配置:
yaml复制deploy:
type: git
repo: https://gitee.com/你的用户名/你的仓库.git
branch: master
这里有个坑要注意:Gitee的仓库地址要用HTTPS格式,SSH格式需要额外配置密钥,对新手不太友好。第一次部署时需要输入Gitee账号密码,建议提前准备好。
4.3 一键部署和更新
部署命令非常简单:
bash复制hexo clean && hexo generate && hexo deploy
我习惯用简写:
bash复制hexo g -d
部署完成后,还需要在Gitee仓库的"服务→Gitee Pages"里手动点击"更新"按钮。这是Gitee Pages和GitHub Pages的一个主要区别,后者是自动更新的。我建议把这个页面加入书签,方便以后每次更新后快速访问。
5. 主题定制与优化
5.1 选择和安装主题
Hexo有大量开源主题可供选择,官方主题库在hexo.io/themes。我最近比较喜欢的是Butterfly和Volantis,前者简洁大方,后者功能丰富。
以Butterfly为例,安装步骤如下:
bash复制git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
然后在_config.yml中启用主题:
yaml复制theme: butterfly
主题通常有自己的配置文件,建议把themes/butterfly/_config.yml复制到项目根目录下,重命名为_config.butterfly.yml,这样升级主题时不会丢失自定义配置。
5.2 基础样式调整
大部分主题都支持通过配置文件修改颜色、字体等样式。以Butterfly为例,可以这样修改:
yaml复制# 修改主题色
theme_color:
enable: true
main: "#49B1F5"
# 字体设置
font:
font-family: "Noto Sans SC", "PingFang SC", "Microsoft YaHei"
我建议初期不要过度定制,先保持主题默认样式,等熟悉了再慢慢调整。有个实用技巧:用Chrome开发者工具实时调试CSS,找到满意的值后再更新配置文件。
6. 内容创作与管理
6.1 文章撰写规范
Hexo的文章是Markdown格式,存放在source/_posts目录下。新建文章可以用命令:
bash复制hexo new "文章标题"
生成的Markdown文件头部有Front-matter区域,用于设置元数据:
markdown复制---
title: 文章标题
date: 2023-07-20 14:00:00
tags: [Hexo, Gitee]
categories: 技术教程
---
我建议养成规范化的标签管理习惯,比如固定用几个大类标签,避免后期标签太多难以管理。文章内容用标准Markdown语法即可,Hexo支持扩展语法如代码高亮、流程图等。
6.2 图片资源管理
处理图片是个常见痛点。我推荐两种方案:
- 使用图床:如SM.MS、阿里云OSS等
- 本地存储:在
source/images下按文章分类存放
本地图片的引用方式:
markdown复制
如果使用图床,建议安装hexo-asset-image插件自动处理路径问题:
bash复制npm install hexo-asset-image --save
7. 进阶技巧与问题排查
7.1 自动化脚本优化
每次部署都要执行多个命令很麻烦,可以在package.json中添加自定义脚本:
json复制"scripts": {
"deploy": "hexo clean && hexo g && hexo d",
"serve": "hexo clean && hexo g && hexo s"
}
这样以后只需要运行:
bash复制npm run deploy
7.2 常见问题解决
问题1:部署后Gitee Pages页面空白
- 检查
public目录是否有生成文件 - 确认Gitee Pages绑定的分支正确
- 尝试强制刷新浏览器缓存(Ctrl+F5)
问题2:主题修改不生效
- 运行
hexo clean清理缓存 - 检查主题配置文件路径是否正确
- 确认修改的是正确的
_config.yml(根目录还是主题目录)
问题3:图片不显示
- 检查图片路径是否正确
- 确认图片是否成功上传
- 如果是相对路径,尝试改为绝对路径
我在实际使用中发现,90%的问题都能通过hexo clean解决。如果遇到奇怪的问题,这是第一个要尝试的解决方案。
