Hexo NexT 部署记录

这篇文章记录旧博客第一次搭建 Hexo NexT 的过程。原来的流程是：本地安装 Hexo，提交源码到 GitHub，触发 GitHub Actions 生成静态文件，再同步到服务器，由 Nginx 提供访问。

现在站点已经迁移到 Astro，但这篇部署笔记仍然保留在归档里，作为旧站建设过程的记录。

Hexo 本地部署

Hexo 需要 Node.js 和 Git。Mac 上可以通过 Homebrew 安装：

brew install git
brew install node

确认版本：

git -v
node -v
npm -v

安装 Hexo CLI：

npm install -g hexo-cli

如果需要使用指定源，也可以这样安装：

npm install -g hexo-cli --registry https://registry.npmmirror.com

初始化 Hexo 项目

在合适的目录下创建项目：

hexo init MyBlog
cd MyBlog
npm install

启动本地服务：

hexo s

默认访问地址是：

http://localhost:4000/

如果端口被占用，可以先查占用进程：

lsof -i:4000

然后停止对应进程，或指定其他端口启动：

hexo s -p 40001

安装 NexT 主题

NexT 可以通过 npm 安装：

npm install hexo-theme-next

安装后，将项目根目录 _config.yml 里的主题改为：

theme: next

Hexo 5 之后推荐使用备用主题配置。可以从主题包复制配置文件：

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

旧站当时使用的是 NexT 的 Muse scheme，并将站点语言设置为：

language: zh-CN

这个语言配置要带国家代码，否则部分中文展示可能出现问题。

GitHub 代码提交

初始化 Git 仓库：

git init
git config user.email "you@example.com"
git config user.name "your-name"

添加远程仓库：

git remote add origin git@github.com:yourname/your-repo.git

提交并推送：

git add .
git commit -m "hexo init"
git push origin main

如果本地有多个 SSH key，可以在 ~/.ssh/config 里给 GitHub 配一个 Host 别名：

Host github-blog
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_blog

测试连接：

ssh -T github-blog

服务器 SSH 配置

当时的服务器系统是 Ubuntu 22.04。为了让 GitHub Actions 可以同步构建产物，需要在服务器上准备可登录的 SSH key。

如果需要允许 root 使用密钥登录，可以检查 SSH 配置：

sudo vim /etc/ssh/sshd_config

配置 Nginx

安装 Nginx：

sudo apt update
sudo apt install nginx

站点配置的核心是把 root 指向静态文件目录：

server {
    listen 80;
    server_name example.com;
    root /var/www/blog;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

重载 Nginx：

sudo nginx -s reload

现在的 Astro 站点仍然可以用类似的 Nginx 静态部署方式，只是构建命令从 hexo generate 换成了 SITE_URL=... npm run build。

GitHub Actions 自动部署

旧博客使用 GitHub Actions 自动生成静态文件并同步到服务器。核心流程是：

检出仓库。
安装 Node。
安装 Hexo。
安装依赖。
执行 hexo clean 和 hexo generate。
使用 SSH / rsync 将 public/ 同步到服务器目录。

示例配置：

name: Deploy Hexo and Publish to Remote Host

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install Hexo
        run: npm install hexo-cli -g

      - name: Install dependencies
        run: npm install

      - name: Generate static files
        run: |
          hexo clean
          hexo generate

      - name: Deploy
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_ACCESS_TOKEN }}
          ARGS: "-rltgoDzvO --delete"
          SOURCE: "public/"
          REMOTE_HOST: ${{ secrets.SERVER_HOST }}
          REMOTE_USER: ${{ secrets.SERVER_USER }}
          TARGET: ${{ secrets.SERVER_TARGET }}
          EXCLUDE: ".git/"

对应的 secrets 需要在 GitHub 仓库设置里维护，例如服务器地址、登录用户、目标目录和 SSH 私钥。

迁移后的变化

旧 Hexo 站点的文章链接是：

/2024/01/24/hexo-init/

当前 Astro 站点统一使用归档详情页：

/archive/hexo-next-deploy/

为了避免旧链接失效，站点会保留从旧地址到新地址的跳转。