Hexo环境搭建与Docker容器化

发表于 分类于

​ 记录从零搭建 Hexo 8.x 博客环境的完整过程，并通过 Docker 容器化实现跨平台的环境一致性，方便在不同设备上快速复现与调试。

环境信息

项目 版本
Node.js 20.x
Hexo 8.1.x
主题 NexT 8.27.0

一、安装 Node.js

Linux (Debian/Ubuntu)

1
2
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS

1
brew install node@20

Windows

从 Node.js 官网 下载 LTS 安装包，或使用 winget：

1
winget install OpenJS.NodeJS.LTS

验证安装

1
2
node --version   # v20.x.x
npm --version    # 10.x.x

二、搭建 Hexo 环境

2.1 全局安装 hexo-cli

1
npm install -g hexo-cli

2.2 初始化项目（如已有项目可跳过）

1
2
3
hexo init HexoBlog
cd HexoBlog
npm install

2.3 安装 NexT 主题（submodule 方式）

使用 git submodule 管理主题，便于跟踪上游更新和版本锁定：

1
git submodule add https://github.com/next-theme/hexo-theme-next themes/next

如果网络不通，可以配置代理：

1
2
3
git -c http.proxy=http://<proxy_host>:<port> \
    -c https.proxy=http://<proxy_host>:<port> \
    submodule add https://github.com/next-theme/hexo-theme-next themes/next

克隆项目后需要初始化 submodule：

1
2
git submodule init
git submodule update

或者克隆时一步到位：

1
git clone --recurse-submodules <your-repo-url>

更新主题到最新版本：

1
2
3
4
5
cd themes/next
git pull origin master
cd ../..
git add themes/next
git commit -m "update next theme"

在 _config.yml 中设置主题：

1
theme: next

2.4 安装依赖并验证

1
2
3
npm install
npx hexo clean && npx hexo generate
npx hexo server

访问 http://localhost:4000 即可预览。

三、升级 Hexo 至 8.x

如果已有 Hexo 7.x 项目，可通过以下步骤升级：

1
2
3
4
5
6
# 使用 npm-check-updates 更新 package.json
npx npm-check-updates -u

# 清除旧依赖并重新安装
rm -rf node_modules package-lock.json
npm install

升级后主要变化（7.x → 8.x）：

包名 旧版本 新版本
hexo ^7.0.0 ^8.1.2
hexo-generator-index ^3.0.0 ^4.0.0
hexo-renderer-marked ^6.0.0 ^7.0.1

验证升级是否成功：

1
2
npx hexo version   # 应显示 hexo: 8.x.x
npx hexo clean && npx hexo generate

四、Docker 容器化运行

使用 Docker 可以将 Hexo 运行环境与宿主机解耦，无论在什么平台上都能获得一致的开发体验。

4.1 前置准备

由于主题通过 git submodule 管理，启动容器前需确保 submodule 已初始化：

1
git submodule init && git submodule update

4.2 快速启动（一行命令）

适合临时调试，容器退出后自动删除：

1
2
3
4
5
6
docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  -p 4000:4000 \
  node:20 \
  bash -c "npm install && npx hexo server"

参数说明：

  • -v $(pwd):/app：将当前项目目录挂载到容器内 /app，源码修改实时生效
  • -p 4000:4000：映射 Hexo 默认端口
  • --rm：容器停止后自动删除

Windows PowerShell 下将 $(pwd) 替换为 ${PWD}。

4.2 使用 docker-compose（推荐）

在项目根目录创建 docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
version: "3"
services:
  hexo:
    image: node:20
    working_dir: /app
    volumes:
      - ./:/app
      - hexo_node_modules:/app/node_modules
    ports:
      - "4000:4000"
    command: bash -c "npm install && npx hexo server"
    stdin_open: true
    tty: true

volumes:
  hexo_node_modules:

启动服务：

1
docker compose up -d

停止服务：

1
docker compose down

关于 node_modules volume： 使用 named volume 隔离 node_modules 可以避免宿主机与容器之间的依赖冲突（例如 macOS 上编译的 native 模块在 Linux 容器中无法使用）。如果希望宿主机和容器共享同一份 node_modules（例如 IDE 需要读取类型定义），去掉 hexo_node_modules:/app/node_modules 这行即可。

4.3 进入容器调试

容器运行后，可以随时进入交互式 shell：

1
2
3
4
5
# 使用 docker compose
docker compose exec hexo bash

# 或者使用容器名
docker exec -it <container_name> bash

进入后可执行任意 Hexo 命令：

1
2
3
4
npx hexo clean        # 清除缓存
npx hexo generate     # 重新生成
npx hexo new "文章标题"  # 创建新文章
npx hexo server       # 启动预览服务

4.4 使用 Dockerfile 自定义镜像（可选）

如果需要预装依赖以加快启动速度，可以创建 Dockerfile：

1
2
3
4
5
6
7
8
9
10
FROM node:20

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install && npm install -g hexo-cli

COPY . .
EXPOSE 4000

CMD ["hexo", "server"]

构建并运行：

1
2
docker build -t my-hexo .
docker run -it --rm -p 4000:4000 -v ./source:/app/source my-hexo

这种方式只挂载 source 目录，适合只需要编辑文章内容的场景。

五、常用操作速查

操作 命令
启动预览 npx hexo server
生成静态文件 npx hexo generate
清除缓存 npx hexo clean
新建文章 npx hexo new "标题"
容器内调试 docker compose exec hexo bash
查看容器日志 docker compose logs -f hexo
重启容器 docker compose restart