Windows 本地搭建部署 Hexo：从入坑到毕业

技术栈：Hexo | Node.js | Git | GitHub Pages | Vercel | netlify
​适合对象​：新手友好，逐步详解

一、环境搭建

1. 安装 Node.js

2. 安装 Git

  • 作用：版本控制与部署工具
  • 下载： Git
  • 安装：全部默认选项

3. 验证安装

1
2
node -v   # 检查 Node.js 版本
git -v     # 检查 Git 版本

二、Hexo 本地部署

1. 安装 Hexo

1
npm install -g hexo-cli  # 全局安装 Hexo 脚手架

2. 初始化项目

1
2
3
4
mkdir hexo      # 创建项目文件夹
cd hexo         # 进入目录
hexo init       # 初始化 Hexo
npm install     # 安装依赖

3. 项目结构

1
2
3
4
5
6
7
my-hexo-blog/
├── source/         # 核心内容（文章/资源）
│   ├── _posts/     # 文章（Markdown）
│   └── images/     # 图片资源
├── themes/         # 主题文件夹（默认 landscape）
├── _config.yml     # 全局配置文件（关键！）
└── package.json    # 项目依赖配置

4. 启动本地服务器

1
hexo server     # 启动服务

访问 http://localhost:4000 预览效果

三、GitHub Pages 部署（外网访问）

1. 仓库准备

  • 源码仓库：.github.io-source（保存 Hexo 源码）
  • 发布仓库：.github.io（自动托管静态页面）
  • Github界面选择create new repository

2. 推送源码到 GitHub

1
2
3
4
5
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<username>/<username>.github.io-source.git
git push -u origin main

3. 生成 GitHub Token

  1. 进入 Settings > Developer settings > Personal Access Tokens
  2. 创建 Token（勾选 repo 权限）
  3. 保存 Token（仅显示一次！）imgimg

4. 部署插件配置

① 安装插件：

1
npm install hexo-deployer-git --save

② 修改 _config.yml（末尾添加）：

1
2
3
4
deploy:
  type: git
  repo: https://<TOKEN>@github.com/<username>/<username>.github.io.git  # 用真实 Token 替换 <TOKEN>
  branch: main

5. 部署到 GitHub Pages

1
hexo clean && hexo deploy

访问 https://.github.io

四、自动化部署（GitHub Actions）（我感觉没啥必要）

1. 创建 Workflow 文件

路径：.github/workflows/deploy.yml 根据具体情况具体修改

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
35
36
37
38
39
40
41
name: Optimized Blog CI/CD

on:
  push:
    branches: [main]
    paths:
      - '*.json'
      - '**.yml'
      - '**/source/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Source
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm ci

      - name: Build Site
        run: |
          npx hexo clean
          npx hexo g

      - name: Add .nojekyll
        run: touch public/.nojekyll

      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          external_repository: <username>/<username>.github.io
          publish_branch: gh-pages
          publish_dir: ./public
          commit_message: "Deploy: ${{ github.sha }}"

2. 配置 Secrets

在 源码仓库 添加私钥：
Settings > Secrets > New secret

  • Name: DEPLOY_TOKEN#确保和文件中设置的一致
  • Value: 粘贴token

五、其他托管平台

▶ Vercel 部署

  1. 注册 Vercel（用 GitHub 账号登录）
  2. 从 GitHub 导入源码仓库
  3. 默认设置部署（自动检测 Hexo）
  4. 访问 https://.vercel.appimgimg

▶ Netlify 部署

  1. 注册 Netlify

  2. 选择 New site from Git > GitHub

  3. 导入仓库并设置构建命令：

    1
    2
    Build command: hexo generate
    Publish directory: public

  4. 访问 https://.netlify.appimgimgimg

六、进阶操作：更换主题

1. 安装新主题（以 Anzhiyu 为例）

1
git clone https://github.com/anzhiyu-c/hexo-theme-anzhiyu.git themes/anzhiyu

2. 安装渲染器

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

3. 启用主题

修改 _config.yml：

1
theme: anzhiyu

4. 同步配置

1
hexo clean && hexo g && hexo d  # 生成并部署

七、高效工作流

▶ 手动部署

1
2
3
hexo new "文章标题"     # 新建文章
hexo clean && hexo g     # 生成静态文件
hexo deploy              # 部署

▶ 自动部署（推荐）

1
2
3
4
hexo new "文章标题"       # 新建文章
git add .                # 添加所有更改
git commit -m "更新文章"  # 提交
git push origin main     # 推送后自动触发 CI/CD

八、问题文档

一·提示：无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本

方法1：临时修改执行策略（推荐）

  1. 以管理员身份打开PowerShell（右键开始菜单 → Windows PowerShell（管理员））。
  2. 输入以下命令修改当前会话的执行策略：
1
Set-ExecutionPolicy RemoteSigned -Scope Process -Force
  1. 重新运行你的命令：
1
npm install -g hexo-cli

方法2：永久修改执行策略

注意：这会永久降低安全性设置，仅当需要频繁运行脚本时使用。

  1. 在管理员PowerShell中执行：
1
Set-ExecutionPolicy RemoteSigned -Force
  1. 确认更改后运行：
1
npm install -g hexo-cli

方法3：单次绕过执行策略

  1. 直接在管理员PowerShell中运行：
1
Start-Process powershell -ArgumentList "-NoProfile -ExecutionPolicy Bypass -Command npm install -g

二·在git push时

1.提示：

error: src refspec main does not match any

error: failed to push some refs to ‘https://github.com//.github.io-source.git‘

重命名本地分支到 main

1
git branch -M main

推送到远程：

1
git push -u origin main

2.提示：fatal: unable to access ‘ https://github.com/tankseck/tankseck.github.io-source.git/‘: Recv failure: Connection was reset

网络问题，可墙解决