tools/hexo-博客搭建指南

一、安装与初始化#

1. 安装 Node.js 和 Git#

确保系统已安装 Node.js 和 Git。

1
# 验证安装
2
node -v
3
npm -v
4
git version

2. 安装 Hexo CLI#

1
npm install -g hexo-cli
2
hexo version

3. 初始化博客#

1
hexo init <folder>
2
cd <folder>
3
npm install

目录结构：

1
├── _config.yml      # 站点配置文件（核心）
2
├── package.json
3
├── scaffolds/       # 模板文件
4
├── source/          # 源码（文章、页面）
5
│   ├── _posts/      # 文章
6
│   └── _drafts/     # 草稿
7
└── themes/          # 主题

二、常用命令#

1
hexo new "文章标题"     # 新建文章
2
hexo new draft "草稿"   # 新建草稿
3
hexo publish "草稿名"   # 发布草稿
4
hexo generate (hexo g)  # 生成静态文件
5
hexo clean              # 清理缓存（public/ 和 db.json）
6
hexo server (hexo s)    # 本地预览，默认 http://localhost:4000
7
hexo deploy (hexo d)    # 部署
8
hexo d -g               # 先 clean 再 generate 再 deploy（常用）
9
hexo new page "about"   # 新建独立页面

三、站点配置 (_config.yml)#

1
# 站点信息
2
title: 我的博客
3
subtitle:
4
description: '博客描述'
5
keywords: '关键词1,关键词2'
6
author: 作者名
7
language: zh-CN
8
timezone: ''
9

10
# URL
11
url: https://yourdomain.com
12
root: /
13
permalink: :year/:month/:day/:title/
14

15
# 主题
16
theme: butterfly
17

18
# 部署
19
deploy:
20
  type: git
21
  repo: ssh://git@your-server-ip:port/home/git/blog.git
22
  branch: master

四、Git SSH 密钥管理#

部署到服务器需要 SSH 免密登录，先管理好本地密钥。

1. 查看 git 配置#

1
git config --list
2
git config user.name
3
git config user.email

2. 初始化用户名和邮箱#

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

3. 查看密钥文件位置#

1
cd ~/.ssh
2
pwd         # 输出 .ssh 文件夹路径
3
ls          # 查看密钥文件

4. 生成密钥（若没有）#

1
ssh-keygen -t rsa -C "你的邮箱"
2
# 一路回车，默认路径即可

生成后在 ~/.ssh/ 下会有：

id_rsa —— 私钥（保密）
id_rsa.pub —— 公钥（配置到服务器/GitHub）

5. 查看公钥#

1
cat ~/.ssh/id_rsa.pub

复制输出内容，添加到服务器的 ~/.ssh/authorized_keys 或 GitHub/Gitee 的 SSH Keys 设置中。

五、部署至自己的服务器#

1. 服务器安装 Git#

1
# CentOS / RHEL
2
yum install git
3

4
# Ubuntu / Debian
5
apt-get install git
6

7
# 验证
8
git version

2. 创建 git 用户#

1
# 添加用户
2
adduser git
3

4
# 赋予 sudo 权限 ，为了安全可以不加
5
chmod 740 /etc/sudoers
6
vim /etc/sudoers
7

8
# 在 root 行下方添加：
9
git   ALL=(ALL)     ALL
10

11
# 按 Esc → :wq 保存退出
12
chmod 400 /etc/sudoers
13

14
# 设置 git 用户密码
15
sudo passwd git

3. 配置 SSH 免密登录#

切换到 git 用户：

1
su - git

创建 .ssh 目录和 authorized_keys 文件：

1
mkdir ~/.ssh
2
vim ~/.ssh/authorized_keys
3
# 将本地 id_rsa.pub 的内容粘贴进去
4
# Esc → :wq 保存退出

设置权限：

1
chmod 600 ~/.ssh/authorized_keys
2
chmod 700 ~/.ssh

本地测试连接：

1
ssh -v git@服务器IP
2
# 能进入 git 用户 shell 即成功

4. 创建 Git 裸仓库#

切回 root 用户，创建仓库和网站根目录：

1
# 创建网站根目录
2
chown -R git:git /opt/1panel/www/sites/zhangzhiwu.cn/index
3
chmod -R 755 /opt/1panel/www/sites/zhangzhiwu.cn/index
4

5
# 创建裸仓库
6
cd /home/git
7
git init --bare blog.git
8
chown -R git:git blog.git

5. 配置 post-receive 钩子（自动部署）#

在 /home/git/blog.git/hooks/ 下创建钩子文件：

1
cd /home/git/blog.git/hooks/
2
vim post-receive

写入以下内容：

1
#!/bin/bash
2
git --work-tree=/opt/1panel/www/sites/zhangzhiwu.cn/index/hexo --git-dir=/home/git/blog.git checkout -f

保存后赋予可执行权限：

1
chmod +x post-receive
2
chown git:git post-receive

作用：每次本地 hexo d 推送代码到仓库，服务器自动将文件更新到 /opt/1panel/www/sites/zhangzhiwu.cn/index/hexo 目录。

6. 本地 Hexo 配置部署#

编辑博客根目录 _config.yml，找到 deploy 段：

1
deploy:
2
  type: git
3
  repo: git@服务器IP:/home/git/blog.git
4
  # 如果 SSH 端口不是默认 22，使用 ssh:// 格式：
5
  # repo: ssh://git@服务器IP:端口/home/git/blog.git
6
  branch: master

安装 git 部署插件：

1
npm install hexo-deployer-git --save

执行部署：

1
hexo clean
2
hexo g
3
hexo d

7. Nginx 配置#

服务器上安装 Nginx，将网站根目录指向 /opt/1panel/www/sites/zhangzhiwu.cn/index/hexo：

1
server {
2
    listen 80;
3
    server_name yourdomain.com;  # 你的域名或IP
4

5
    root /opt/1panel/www/sites/zhangzhiwu.cn/index/hexo;
6
    index index.html index.htm;
7

8
    location {
9
        try_files $uri $uri/ $uri/index.html =404;
10
    }
11

12
    # 开启 gzip 压缩
13
    gzip on;
14
    gzip_types text/plain text/css application/json application/javascript text/xml;
15
}

重载 Nginx：

1
nginx -t          # 测试配置
2
nginx -s reload   # 重载

访问 http://yourdomain.com 即可看到博客。

六、主题安装（以 Butterfly 为例）#

1. 安装#

1
npm install hexo-theme-butterfly

2. 启用#

在 _config.yml 中修改：

1
theme: butterfly

3. 主题配置#

创建 _config.butterfly.yml（优先级高于主题内置配置）。

七、常见问题#

问题	解决
`ERROR Deployer not found: git`	`npm install hexo-deployer-git --save`
部署后页面空白/404	检查 Nginx root 目录是否指向正确路径（`/opt/1panel/www/sites/zhangzhiwu.cn/index/hexo`）
SSH 连接超时	检查服务器安全组/防火墙是否放行 SSH 端口
推送成功但页面未更新	检查 post-receive 钩子权限（`chmod +x`）和路径
`Permission denied (publickey)`	本地公钥未添加到服务器 `authorized_keys`，或权限不是 600
本地预览正常部署后样式丢失	执行 `hexo clean` 清理缓存后重新 `hexo g`

八、快速部署流程总结#

1
本地                              服务器
2
────                              ────
3
hexo clean                        1. yum install git
4
hexo g                            2. adduser git + 配置 SSH
5
hexo d ──── git push ────────▶    3. git init --bare blog.git
6
                                  4. post-receive 钩子
7
                                  5. 自动 checkout 到 /opt/1panel/www/sites/zhangzhiwu.cn/index/hexo
8
                                  6. Nginx 指向 /opt/1panel/www/sites/zhangzhiwu.cn/index/hexo
9

10
用户访问 yourdomain.com ◀──────── Nginx 返回静态文件

九、Butterfly 音乐播放器#

1. 插件安装#

1
npm install --save hexo-tag-aplayer

2. 配置文件修改#

在 Hexo 根目录 _config.yml 中添加：

1
aplayer:
2
  meting: true
3
  asset_inject: false

在主题配置文件中开启：

1
# Inject the css and script (aplayer/meting)
2
aplayerInject:
3
  enable: true
4
  per_page: true

3. 普通界面播放器#

1
{% meting "7422861869" "netease" "playlist" "autoplay" "mutex:false" "listmaxheight:400px" "preload:none" "theme:#ad7a86"%}

常用选项：

参数	可选值	说明
server	netease, tencent, kugou, xiami, baidu	音乐平台，建议网易云
type	song, playlist, album, search, artist	类型
id	数字	歌单/歌曲 ID，从网页版 URL 获取
lrcType	-1	默认显示歌词，fixed 模式下适用

也可直接使用 HTML：

1
<div class="aplayer" data-id="000PeZCQ1i4XVs" data-server="tencent" data-type="artist" data-preload="auto" data-theme="#3F51B5"></div>

4. 全局吸底播放器#

把代码插入到主题配置文件的 inject.bottom：

1
inject:
2
  head:
3
  bottom:
4
    - <div class="aplayer no-destroy" data-id="7422861869" data-server="netease" data-type="playlist" data-fixed="true" data-autoplay="true" data-lrcType="-1"> </div>

5. 切换页面音乐不中断#

1
pjax:
2
  enable: true
3
  exclude:

6. Aplayer 完整配置参数#

Name	Default	Description
container	`document.querySelector('.aplayer')`	player container
fixed	false	enable fixed mode
mini	false	enable mini mode
autoplay	false	audio autoplay
theme	’#b7daff’	main color
loop	’all’	player loop play: ‘all’, ‘one’, ‘none’
order	’list’	play order: ‘list’, ‘random’
preload	’auto’	values: ‘none’, ‘metadata’, ‘auto’
volume	0.7	default volume
mutex	true	prevent multiple players at same time
lrcType	0	lrc type
listFolded	false	whether list should folded at first
listMaxHeight	-	list max height
storageName	’aplayer-setting’	localStorage key