Hexo + Stellar 博客从零搭建到阿里云部署完整教程

本文是一篇完整可执行的 Hexo 博客搭建教程，覆盖本地初始化、主题配置、写作工作流、双分支部署架构、阿里云服务器 + Git Hook 自动发布、OSS/CDN 接入等全部环节。每一步都给出可以直接复制执行的命令，关键节点配 ASCII 流程图说明原理。

1. 环境准备

1.1 安装 Git

# macOS（自带或 Homebrew）
git --version       # 应 ≥ 2.20
# 或：brew install git

# CentOS / 阿里云服务器
yum install -y git

# Ubuntu / Debian
apt install -y git

1.2 安装 Node.js（推荐 LTS）

# 推荐用 nvm 管理多版本（避免污染全局）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc    # macOS 默认 zsh；如果是 bash 改成 source ~/.bashrc

nvm install 22
nvm use 22
node -v            # 应显示 v22.x.x
npm -v

1.3 全局安装 hexo-cli

npm install -g hexo-cli
hexo -v

⚠️ macOS 用户若 npm install -g 报权限错误，使用 sudo 或参考 nvm_node 笔记切换到 nvm 安装的 Node。

2. 本地初始化博客项目

2.1 初始化目录结构

mkdir ~/Documents/IdeaProjects && cd ~/Documents/IdeaProjects
hexo init blog-hexo
cd blog-hexo

hexo init 会自动生成以下关键文件：

blog-hexo/
├── _config.yml        # 站点主配置（标题、URL、deploy 等）
├── package.json       # 依赖与脚本
├── scaffolds/         # 文章模板（draft / post / page）
├── source/            # 源文件（你编辑的全部内容在这里）
│   ├── _posts/        # 博客文章（.md）
│   └── _data/         # 站点数据
├── themes/            # 主题目录（可选，Stellar 通过 npm 安装）
└── public/            # 编译产物（hexo g 生成，不要手动改）

2.2 安装 Stellar 主题

Stellar 通过 npm 安装到 node_modules，无需 git clone：

npm install hexo-theme-stellar

_config.yml 里切换主题：

theme: stellar

新建主题配置文件（避免升级时被覆盖）：

cp node_modules/hexo-theme-stellar/_config.yml ./_config.stellar.yml

之后只编辑 ./_config.stellar.yml，不动 node_modules 里的那份。

2.3 配置站点基本信息

_config.yml 关键字段：

title: 你的博客名
subtitle: 副标题
description: 站点描述
keywords: 关键词1,关键词2
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
url: https://your-domain.com/         # 最终对外的 URL

2.4 第一次本地预览

hexo clean && hexo g && hexo s

打开浏览器访问 http://localhost:4000，确认默认主题已生效。

3. 写作工作流

3.1 新建文章

hexo new "我的第一篇文章"
# 或显式指定分类
hexo new "博客搭建" -p source/_posts/blog/my-first-post

会生成 source/_posts/<slug>/index.md 或类似路径，front matter 模板：

---
title: 我的第一篇文章
date: 2026-10-03 21:30:00
tags: []
categories: []
---

正文...

3.2 常用写作命令

操作	命令
新建文章	`hexo new "<title>"`
启动本地预览（带热更新）	`hexo s`
清理 `public/`	`hexo clean`
生成静态文件	`hexo g`
生成 + 部署	`hexo clean && hexo g && hexo d`
生成草稿	`hexo new draft "<title>"`
发布草稿	`hexo publish "<title>"`

4. 部署架构总览（核心原理）

在写命令之前，先看完整链路。理解架构比记住命令更重要——出问题排查时全靠这张图：

4.1 整体架构图

┌─────────────────────────┐                  ┌────────────────────────────────┐
│   本地工作区 (Mac)        │                  │   阿里云 ECS ()    │
│                         │                  │                                │
│  source/_posts/*.md      │                  │                                │
│       │                 │                  │                                │
│       ▼                 │                  │                                │
│  hexo g ───► public/    │                  │                                │
│       │                 │                  │                                │
│       ▼                 │                  │                                │
│  hexo-deployer-git      │   SSH push       │  /home/git/hexo.git            │
│       │                 │  (id_rsa 公钥)   │   (bare 仓库)                   │
│  ┌────────────────────┐ │ ───────────────► │       │                        │
│  │ .deploy_git/       │ │                  │       │ post-receive hook      │
│  │  (影子仓库,         │ │                  │       ▼                        │
│  │   master 分支)      │ │                  │  git checkout -f master        │
│  └────────────────────┘ │                  │       │                        │
│                         │                  │       ▼                        │
│                         │                  │  /home/www/hexo/               │
│                         │                  │   (Web 根目录)                  │
│                         │                  │       │                        │
└─────────────────────────┘                  │       ▼                        │
                                              │  Nginx ──► https://your-domain │
                                              │       │                        │
                                              │       ▼                        │
                                              │  (可选) ossutil 定时同步        │
                                              │       │                        │
                                              │       ▼                        │
                                              │  阿里云 OSS + CDN              │
                                              └────────────────────────────────┘

4.2 双分支策略详解

本项目采用 main（源码，本地专用）+ master（部署产物，远端专用） 的双分支架构：

分支	类型	远端是否存在	作用
`main`	本地源码分支	❌ 不上远端	Hexo 工程源文件（_config.yml、文章、主题、依赖）
`master`	远端部署分支	✅ origin/HEAD	`hexo d` 自动推送的静态产物

为什么两条分支是独立的？ 因为 hexo-deployer-git 在内部维护了一个影子仓库 .deploy_git/，它永远只有一个分支叫 master，每次部署都是把 master 强制推到 origin。origin 上的 master 被反复 force-push，与 main 完全不共享历史（git merge-base 为空）。

      ┌─────────── main（本地源码）────────────┐
      │                                       │
.git/refs/heads/main                          │
      │                                       │
      │  你手工 commit                        │
      │                                       │
      ▼                                       │
23942f13b0 手工测试                            │
15b43a438f 初始化干净提交历史                   │
                                               
                                            
      ┌─────────── master（部署产物）──────────┐
      │                                       │
.deploy_git/refs/heads/master                  │
      │                                       │
      │  hexo-deployer-git 自动 commit          │
      │  提交信息: Site updated: <时间戳>       │
      ▼                                       │
cf3fb32454 Site updated: 2026-10-03 21:54:42   │
a4371bafa5 Site updated: 2026-10-03 21:27:21   │
...                                            │
df89973da3 First commit                         │

4.3 推送时序图

你   hexo d   hexo-deployer-git   .deploy_git/    git/ssh      阿里云 ECS
│     │              │                │            │              │
│     │              │                │            │              │
├─────┼──────────────┼────────────────┼────────────┼──────────────┤
│     │ 触发部署      │                │            │              │
│     ├─────────────►│                │            │              │
│     │              │ 清空工作区      │            │              │
│     │              ├───────────────►│            │              │
│     │              │ 复制 public/    │            │              │
│     │              ├────────═══════►│            │              │
│     │              │ git add .       │            │              │
│     │              ├────────═══════►│            │              │
│     │              │ git commit      │            │              │
│     │              ├═══════════════►│            │              │
│     │              │                │ 强制推送    │              │
│     │              ├────────────────┼──────────►│              │
│     │              │                │            │ SSH 认证     │
│     │              │                │            ├─────────────►│
│     │              │                │            │ 接收 commit  │
│     │              │                │            ├─────────────►│
│     │              │                │            │ 触发 hook    │
│     │              │                │            │   post-receive
│     │              │                │            │     │
│     │              │                │            │     ▼
│     │              │                │            │   git checkout -f
│     │              │                │            │     → /home/www/hexo
│     │              │                │            │              │
│     │              │                │            │   (可选) ossutil
│     │              │                │            │     → OSS bucket
│     │              │                │            │              │
│     │  返回成功     │                │            │              │
│◄────┼──────────────┤                │            │              │
│     │              │                │            │              │

5. 本地部署配置（hexo-deployer-git）

5.1 安装插件

npm install hexo-deployer-git --save

5.2 配置 `_config.yml`

deploy:
  type: git
  repo: git@你的服务器IP:/home/git/hexo.git
  branch: master
  message: 'Site updated: {{ now("yyyy-MM-dd HH:mm:ss") }}'

{{ now("...") }} 是 hexo-deployer-git 的模板语法，提交时会替换成当前时间。

5.3 准备 SSH 公钥

# 如果你还没有 id_rsa
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

# 查看公钥（稍后要加到服务器的 authorized_keys）
cat ~/.ssh/id_rsa.pub

6. 阿里云服务器配置（Git Hook 自动发布）

6.1 服务器端建 bare 仓库

SSH 登录服务器后：

# 创建 git 用户（如果没有）
useradd -m git          # 或用现有用户
passwd git

# 切换到 git 用户
su - git

# 建 bare 仓库
mkdir -p /home/git/hexo.git
cd /home/git/hexo.git
git init --bare

6.2 配置 post-receive 钩子

# 写入 hook
cat > /home/git/hexo.git/hooks/post-receive << 'EOF'
#!/bin/bash
# 强制把 master 检出到 Web 根目录
git --work-tree=/home/www/hexo --git-dir=/home/git/hexo.git checkout -f
EOF

# 加执行权限
chmod +x /home/git/hexo.git/hooks/post-receive

6.3 准备 Web 根目录

# 创建站点目录（root 用户）
mkdir -p /home/www/hexo
chown -R git:git /home/www/hexo

6.4 把本地公钥加到服务器

# 在服务器上（git 用户）
mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat >> ~/.ssh/authorized_keys << 'EOF'
ssh-rsa AAAA... your-email@example.com    # 粘贴本地 ~/.ssh/id_rsa.pub 内容
EOF
chmod 600 ~/.ssh/authorized_keys

7. Web 服务配置（Nginx）

7.1 安装 Nginx

yum install -y nginx       # CentOS
# 或
apt install -y nginx       # Ubuntu

7.2 配置站点 server 块

cat > /etc/nginx/conf.d/hexo.conf << 'EOF'
server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    
    root /home/www/hexo;
    index index.html;
    
    # 静态资源缓存
    location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2)$ {
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }
    
    # SPA 风格 history 路由兜底
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # Hexo 默认 404 页面
    error_page 404 /404.html;
}
EOF

nginx -t            # 校验配置
systemctl reload nginx

7.3 申请 HTTPS 证书（可选但推荐）

# 用 acme.sh 免费申请
curl https://get.acme.sh | sh
source ~/.bashrc
acme.sh --issue -d your-domain.com -d www.your-domain.com --nginx
acme.sh --install-cert -d your-domain.com \
    --key-file       /etc/nginx/ssl/your-domain.com.key \
    --fullchain-file /etc/nginx/ssl/your-domain.com.crt \
    --reloadcmd      "systemctl reload nginx"

Nginx 改为 443 监听 + HTTP 自动跳转 HTTPS，参考 applicationSSL 笔记。

8. （可选）OSS + CDN 加速

如果用户主要在大陆访问，建议加阿里云 OSS + CDN：

8.1 ossutil 批量同步脚本

服务器上 ~/.ossutilconfig：

[Credentials]
language=EN
endpoint=oss-cn-hangzhou.aliyuncs.com
accessKeyID=你的AccessKeyID
accessKeySecret=你的AccessKeySecret

定时同步脚本 /home/git/oss-sync.sh：

#!/bin/bash
set -e
SRC=/home/www/hexo
DEST=oss://你的bucket名称/

# 把本地 web 根目录推到 OSS（排除 .git 等）
ossutil cp -r --force --update $SRC $DEST \
    --exclude ".git/*" \
    --exclude "*.log"

chmod +x /home/git/oss-sync.sh
# 写入 crontab，每分钟同步一次
crontab -e
* * * * * /home/git/oss-sync.sh >> /var/log/oss-sync.log 2>&1

8.2 CDN 配置

在阿里云 CDN 控制台：

添加域名 cdn.your-domain.com
回源 OSS bucket
缓存策略：HTML 5 分钟，静态资源 30 天
HTTPS 证书与源站共用

修改 applicationSSL 笔记中的 Nginx 配置，让 your-domain.com 反代到 CDN。

9. 执行第一次部署

回到本地：

# 第一次部署前，确保 main 工作区是干净的
git status

# 触发部署
hexo clean && hexo g && hexo d

预期日志：

INFO  Deploying: git
INFO  Clearing .deploy_git folder...
INFO  Copying files from public folder...
INFO  Copying files from extend folder...
[master (root-commit) <hash>] Site updated: 2026-10-03 21:54:42
 <new hash>..<new hash>  master -> master
Branch 'master' set up to track remote 'master' from 'origin'.
INFO  Deploy done: git

部署完成后：

浏览器访问 http://your-domain.com 看到博客
服务器 /home/www/hexo/ 目录下已有完整静态文件
git log origin/master 看到最新 Site updated: 提交

10. 常见问题排查

Q1：deploy 时报 `Permission denied (publickey)`

原因：服务器的 ~/.ssh/authorized_keys 没有你的公钥。

排查：

# 本地测试 SSH
ssh -vT git@your-server-ip
# 看 debug1: Offering public key: ... 行，确认公钥路径

修复：把 cat ~/.ssh/id_rsa.pub 的输出加到服务器的 ~/.ssh/authorized_keys。

Q2：部署成功但网站没更新

排查清单：

服务器 ls -la /home/www/hexo/ 看是否有最近的文件
cat /home/git/hexo.git/hooks/post-receive 看 hook 内容是否正确
ls -l /home/git/hexo.git/hooks/post-receive 看是否有 +x

手动执行 hook 看是否报错：

sudo -u git /home/git/hexo.git/hooks/post-receive

Nginx 缓存：nginx -s reload

Q3：本地 main 分支误推到远端导致 deploy 报错

因为 hexo-deployer-git 的影子仓库 .deploy_git/ 跟踪的是 master，和 main 无关。但如果你手动 git push origin main，远端会出现一个你不想要的 main 分支。删除：

# 服务器上
git -C /home/git/hexo.git branch -D main

或者在 Gitea/GitLab 仓库设置里直接删。

Q4：fork 提交导致 IntelliJ 图上显示”孤儿线”

如果你的 main 历史曾经 merge 过 origin/master 的老 commit，而 origin/master 后来被 hexo-deployer-git force-push 过，会出现 merge-base 为空但 main 内部有指向旧 master 的引用。清理方法：

# 用 orphan 重建 main（保留当前文件，丢弃 main 历史）
git checkout --orphan clean-main main
git commit -m "初始化干净提交历史"
git branch -D main
git branch -m clean-main main

11. 进阶：本地 main 分支的备份策略

由于 main 默认不上远端（避免和 master 冲突），所有源码只在本地——这是个单点故障。建议至少做以下一种备份：

方案	命令
推到 Gitea 私有仓库	`git remote add gitea git@gitea-url:user/blog-hexo.git && git push -u gitea main`
推到 GitHub 私有仓库	同上，地址换成 github
推到阿里云 OSS	用 `ossutil cp -r . oss://bucket/blog-hexo-backup/` 定期备份
用 Time Machine	macOS 自带，覆盖整个 `~/Documents/IdeaProjects`

⚠️ 不管用哪种方案，不要把 main 推到 origin（origin 是部署服务器，给 master 用）。要么新加一个 remote，要么用非 Git 方式备份。

12. 一图总结

你写文章（source/_posts/*.md）
     │
     ▼
hexo clean && hexo g   ← 本地编译
     │
     ▼
hexo d   ← hexo-deployer-git 把 public/ 推 origin:master
     │
     ▼   SSH (id_rsa)
阿里云 bare 仓库：/home/git/hexo.git
     │
     ▼   触发 post-receive hook
git checkout -f master → /home/www/hexo/
     │
     ▼   Nginx 读取
用户浏览器看到 https://your-domain.com

（可选）ossutil 定时把 /home/www/hexo/ 推到 OSS → CDN → 用户

到这里，整个 Hexo 博客的搭建、双分支部署架构、阿里云服务器配置、OSS/CDN 加速就全部打通了。后续写文章只需要在 main 分支上编辑 source/_posts/，然后 ./deploy.sh（或 hexo d）一键发布。