Hexo | zZw's Blog

一、安装与初始化

1. 安装 Node.js 和 Git

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

# 验证安装
node -v
npm -v
git version

2. 安装 Hexo CLI

1 2	npm install -g hexo-cli hexo version

3. 初始化博客

1
2
3

hexo init <folder>
cd <folder>
npm install

目录结构：

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

二、常用命令

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

三、站点配置 (_config.yml)

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

# URL
url: https://yourdomain.com
root: /
permalink: :year/:month/:day/:title/

# 主题
theme: butterfly

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

四、Git SSH 密钥管理

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

1. 查看 git 配置

1
2
3

git config --list
git config user.name
git config user.email

2. 初始化用户名和邮箱

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

3. 查看密钥文件位置

1
2
3

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

4. 生成密钥（若没有）

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

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

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

5. 查看公钥

1	cat ~/.ssh/id_rsa.pub

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

五、部署至自己的服务器（重点）

1. 服务器安装 Git

# CentOS / RHEL
yum install git

# Ubuntu / Debian
apt-get install git

# 验证
git version

2. 创建 git 用户

# 添加用户
adduser git

# 赋予 sudo 权限
chmod 740 /etc/sudoers
vim /etc/sudoers
# 在 root 行下方添加：
# git   ALL=(ALL)     ALL
# 按 Esc → :wq 保存退出
chmod 400 /etc/sudoers

# 设置 git 用户密码
sudo passwd git

3. 配置 SSH 免密登录

切换到 git 用户：

su - git

创建 .ssh 目录和 authorized_keys 文件：

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

设置权限：

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

本地测试连接：

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

4. 创建 Git 裸仓库

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

# 创建网站根目录
mkdir /home/hexo
chown git:git /home/hexo
chmod 755 /home/hexo

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

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

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

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

写入以下内容：

1 2	#!/bin/bash git --work-tree=/home/hexo --git-dir=/home/git/blog.git checkout -f

保存后赋予可执行权限：

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

作用：每次本地 hexo d 推送代码到仓库，服务器自动将文件更新到 /home/hexo 目录。

6. 本地 Hexo 配置部署

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

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

安装 git 部署插件：

1	npm install hexo-deployer-git --save

执行部署：

1
2
3

hexo clean
hexo g
hexo d

报错 ERROR Deployer not found: git → 执行 npm install hexo-deployer-git --save

7. Nginx 配置

服务器上安装 Nginx，将网站根目录指向 /home/hexo：

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

    root /home/hexo;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ $uri/index.html =404;
    }

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

重载 Nginx：

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

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

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

1. 安装

1	npm install hexo-theme-butterfly

2. 启用

在 _config.yml 中修改：

1	theme: butterfly

3. 主题配置

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

1 2	# 具体配置参考 Butterfly 官方文档 # https://butterfly.js.org/

七、常见问题

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

八、快速部署流程总结

本地                              服务器
────                              ────
hexo clean                        1. yum install git
hexo g                            2. adduser git + 配置 SSH
hexo d ──── git push ────────▶    3. git init --bare blog.git
                                  4. post-receive 钩子
                                  5. 自动 checkout 到 /home/hexo
                                  6. Nginx 指向 /home/hexo
                                  
用户访问 yourdomain.com ◀──────── Nginx 返回静态文件