📝 保姆级教程！Mac + Hexo + GitHub + Hugging Face 打造全自动静态博客 (完整复盘版)

前言

为什么要这么折腾？

  • GitHub Pages：国内访问慢，百度不收录。
  • Vercel：容易被墙，IP 不稳定。
  • Hugging Face Space (HFS)：速度快，免费，自带 CDN，是目前最香的静态托管方案。

但这套方案并没有想象中那么顺滑。Hugging Face 的服务器逻辑非常“直男”，导致迁移过程中遇到了无数 302 跳转、404 报错、侧边栏失效等问题。

本文将完全还原搭建过程，手把手教你在 Mac 上跑通这条流水线。

第一步：Mac 环境与 Homebrew 避坑 🍺

想在 Mac 上玩开发，Homebrew 是绕不过去的坎。

1. 安装 Homebrew

官方命令网络不通，推荐使用国内镜像脚本：

1
/bin/zsh -c "$(curl -fsSL [https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh](https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh))"

安装过程中选择 中科大 或 清华 镜像源，速度飞快。

🚨 避坑重点：配置环境变量

安装脚本跑完后，千万别直接关掉窗口！ 仔细看最后的提示，它会让你执行类似下面这两行命令（把 brew 加到系统路径里）：

1
2
3
# 注意：把下面的 "你的用户名" 换成你实际的用户名
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/你的用户名/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

如果不执行这一步，你输入 brew 时终端会报错 command not found。

2. 安装 Node.js 和 Git

环境配好后，一行命令搞定：

1
brew install node git

检查是否成功：node -v 和 git --version。

3. 安装 Hexo 脚手架

1
npm install -g hexo-cli

第二步：Hexo + Butterfly 本地初始化 🦋

1. 建站与安装主题

1
2
3
4
5
6
7
8
9
hexo init myblog
cd myblog
npm install

# 安装 Butterfly 主题
npm i hexo-theme-butterfly --save

# ⚠️ 必装渲染器：没有这两个，主题跑不起来
npm install hexo-renderer-pug hexo-renderer-stylus --save

2. 启用主题

修改根目录 _config.yml：

1
theme: butterfly

3. 本地测试

1
hexo clean && hexo s

访问 http://localhost:4000，确认本地环境没问题。

第三步：连接 GitHub（源码托管） 📦

这是自动化的起点。注意：GitHub 现在不支持密码验证，必须申请 Token！

1. 创建 GitHub 仓库

在 GitHub 新建仓库 blog-source，强烈建议设为 Private（私有），保护你的配置文件。

2. 🚨 避坑重点：获取 GitHub Personal Access Token

我们在本地推送代码时，需要用 Token 当密码。

  1. 点击 GitHub 头像 -> Settings -> 左下角 Developer settings。
  2. 选择 Personal access tokens -> Tokens (classic)。
  3. 点击 Generate new token (classic)。
  4. Note: 随便填（如 mac-hexo-push）。
  5. Expiration: 建议选 No expiration（永不过期）。
  6. Scopes (权限)：务必勾选 repo (全选 repo 下的所有项)。
  7. 点击生成，立即复制那个 ghp_ 开头的字符串（只显示一次，丢了要重来）。

3. 建立连接并推送

在博客根目录下执行：

1
2
3
4
5
6
7
8
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin [https://github.com/你的用户名/blog-source.git](https://github.com/你的用户名/blog-source.git)

# 🚀 推送 (关键时刻)
git push -u origin main

此时终端会让你输入用户名和密码：

  • Username: 你的 GitHub 用户名
  • Password: 粘贴刚才申请的 ghp_xxxx Token (输入时不会显示，直接回车)

第四步：连接 Hugging Face（自动部署） 🚀

1. 准备 HFS 空间

  1. 注册 Hugging Face。
  2. 创建 Space：SDK 选择 Static (必选)，公开性选 Public。

2. 获取 HF Access Token

为了让 GitHub 能把代码推送到 HFS，我们需要给它授权。

  1. HF -> Settings -> Access Tokens -> Create new token。
  2. Type 选 Write (写权限) -> 复制 Token。

3. 配置 GitHub Secrets

  1. GitHub 仓库 -> Settings -> Secrets and variables -> Actions。
  2. 新建 Secret -> Name: HF_TOKEN -> Value: 粘贴 HF 的 Token。

4. 创建自动化流水线

新建文件 .github/workflows/deploy.yml，填入以下内容。
这样以后你只需要往 GitHub 推送，它就会自动帮你发布到 HFS。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
name: Deploy to Hugging Face
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Install Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install Dependencies
      run: npm install
      
    - name: Build Hexo
      run: npx hexo generate
      
    - name: Push to Hugging Face
      env:
        HF_TOKEN: ${{ secrets.HF_TOKEN }}
      run: |
        cd public
        git init
        git config user.name "GitHub Actions"
        git config user.email "actions@github.com"
        git add .
        git commit -m "Auto deploy"
        # ⚠️ 换成你的 HFS 地址：https://用户名:$HF_TOKEN@huggingface.co/spaces/用户名/空间名
        git push --force https://你的用户名:$HF_TOKEN@huggingface.co/spaces/你的用户名/空间名 main

第五步：解决 HFS 特有的 302/404 问题 (避坑指南) 🛠️

Hugging Face 的静态服务器不支持目录路径（如 /tech/），只认文件（/tech/index.html）。如果不解决，侧边栏和分类点击全是报错。

1. 修改 _config.yml 锁定路径

1
2
3
4
5
6
7
8
9
10
11
12
13
url: [https://你的空间.static.hf.space](https://你的空间.static.hf.space)
root: /
relative_link: false  # 关掉相对路径，防止套娃
pretty_urls:
  trailing_index: true # 强制补全 index.html
  trailing_html: true

# 简单的分类映射
category_map:
  科技: tech
  影视: film
  English: english
  Private: private

2. 手动创建分类“地基”

在 source/categories/ 下创建 tech/index.md 等文件，确保 layout: category。这是为了让空分类也能显示。

3. 终极 JS 补丁 (解决 302 跳转)

Butterfly 生成的侧边栏链接通常不带 .html，这会触发 HFS 的 302 错误。
打开 _config.butterfly.yml，在 inject: bottom 处加入这段 JS，强制修正链接：

1
2
3
4
inject:
  head:
  bottom:
    - <script>(function(){const fixHfsLink=function(){const links=document.querySelectorAll('#aside-content a, .card-category-list-link, .site-data a, .article-sort-item-title, .category-list-link');links.forEach(link=>{let href=link.getAttribute('href')||link.closest('a')?.getAttribute('href');if(href&&href.endsWith('/')&&!href.startsWith('http')){link.setAttribute('href',href+'index.html');}});};fixHfsLink();document.addEventListener('pjax:complete',fixHfsLink);document.addEventListener('click',function(e){const t=e.target.closest('a');if(t){let href=t.getAttribute('href');if(href&&href.endsWith('/')&&!href.startsWith('http')&&!href.endsWith('index.html')){t.setAttribute('href',href+'index.html');}}},true);})();</script>

总结

至此，我们的全自动博客系统就搭建完成了！

以后的写作流程非常丝滑：

  1. Mac 本地写作：hexo new "文章名"
  2. 提交代码：git add . -> git commit -m "up" -> git push
  3. 收工！ GitHub 会自动把文章编译好并推送到 Hugging Face。

这套方案虽然初期配置麻烦，但一劳永逸，既享受了 GitHub 的版本管理，又享受了 HFS 的高速访问。