🖥️ 本地环境详细准备步骤（Windows）

1. 系统要求检查

  • Windows 10 或更高版本
  • 至少 8GB RAM（推荐 16GB）
  • 至少 10GB 可用磁盘空间

2. 安装 PowerShell 7

方法一：Microsoft Store（推荐）

  1. 打开 Microsoft Store
  2. 搜索 “PowerShell”
  3. 选择 “PowerShell 7+”，点击安装
  4. 安装后，在开始菜单找到 PowerShell 7 并启动

方法二：手动安装

1
2
3
4
5
6
# 1. 下载 PowerShell 7 安装包
# 访问：https://github.com/PowerShell/PowerShell/releases
# 下载：PowerShell-7.x.x-win-x64.msi

# 2. 右键点击安装包，选择"以管理员身份运行"
# 3. 按照向导完成安装

验证安装：

1
2
3
# 打开 PowerShell 7，运行：
$PSVersionTable.PSVersion
# 应该显示 7.x.x 版本

3. 安装 Visual Studio Code

步骤：

  1. 下载 VSCode

  2. 安装 VSCode

    1
    2
    3
    4
    5
    6
    # 双击安装包 VSCodeUserSetup-x64-x.x.x.exe
    # 安装选项：
    # ☑ 将"通过 Code 打开"操作添加到 Windows 资源管理器文件上下文菜单
    # ☑ 将"通过 Code 打开"操作添加到 Windows 资源管理器目录上下文菜单
    # ☑ 将 Code 注册为受支持的文件类型的编辑器
    # ☑ 添加到 PATH（重启后生效）

  3. 安装必要扩展
    打开 VSCode，按 Ctrl+Shift+X，搜索并安装：

    • Chinese (Simplified) Language Pack（中文语言包）
    • GitHub Theme（可选主题）
    • GitLens（Git 增强）
    • Hexo Utils（Hexo 工具）
    • Markdown All in One（Markdown 增强）
    • Prettier（代码格式化）

4. 安装 Git

步骤：

  1. 下载 Git

    1
    2
    # 访问：https://git-scm.com/download/win
    # 下载：Git-x.x.x-64-bit.exe

  2. 安装 Git（详细配置）

    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
    安装选项：
    1. 选择组件：
      ☑ Git Bash Here
      ☑ Git GUI Here
      ☑ Git LFS (Large File Support)
      ☑ Associate .git* configuration files with the default text editor
      ☑ Associate .sh files to be run with Bash

    2. 选择默认编辑器：
      ▸ Use Visual Studio Code as Git's default editor

    3. 调整 PATH 环境：
      ▸ Git from the command line and also from 3rd-party software

    4. 选择 HTTPS 传输后端：
      ▸ Use the OpenSSL library

    5. 配置行尾符号转换：
      ▸ Checkout Windows-style, commit Unix-style line endings

    6. 配置终端模拟器：
      ▸ Use Windows' default console window

    7. 其他选项：
      ☑ Enable file system caching
      ☑ Enable symbolic links

  3. 配置 Git 用户信息

    1
    2
    3
    4
    # 打开 PowerShell 7
    git config --global user.name "你的GitHub用户名"
    git config --global user.email "你的GitHub邮箱"
    git config --global credential.helper store  # 保存凭证

  4. 验证安装

    1
    2
    git --version
    # 应该显示：git version 2.x.x.windows.1

5. 安装 Node.js v24.13.0

方法一：使用 nvm-windows（推荐）

  1. 安装 nvm-windows

    1
    2
    3
    4
    5
    6
    # 1. 卸载现有 Node.js（如果已安装）
    # 2. 下载 nvm-setup.exe
    # 访问：https://github.com/coreybutler/nvm-windows/releases
    # 下载：nvm-setup.exe

    # 3. 以管理员身份运行安装，使用默认设置

  2. 安装 Node.js 24.13.0

    1
    2
    3
    4
    # 打开 PowerShell 7（管理员权限）
    nvm install 24.13.0
    nvm use 24.13.0
    nvm on  # 启用 Node.js 版本管理

  3. 验证安装

    1
    2
    node --version  # 应该显示：v24.13.0
    npm --version   # 应该显示：10.x.x

方法二：直接安装

  1. 下载安装包

    1
    2
    # 访问：https://nodejs.org/download/release/v24.13.0/
    # 下载：node-v24.13.0-x64.msi

  2. 安装 Node.js

    1
    2
    3
    4
    5
    6
    7
    安装选项：
    1. 接受许可协议
    2. 选择安装路径（默认：C:\Program Files\nodejs\）
    3. 自定义安装，确保勾选：
      ☑ npm package manager
      ☑ Add to PATH
      ☑ Automatically install the necessary tools...

6. 配置 npm 和镜像源

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看当前配置
npm config list

# 设置淘宝镜像（国内推荐）
npm config set registry https://registry.npmmirror.com

# 设置 npm 全局安装路径
npm config set prefix "C:\Users\你的用户名\AppData\Roaming\npm"

# 设置缓存路径
npm config set cache "C:\Users\你的用户名\AppData\Roaming\npm-cache"

# 验证配置
npm config get registry

7. 安装 Hexo CLI 8.1.1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 1. 安装 Hexo CLI（全局安装）
npm install -g hexo-cli@8.1.1

# 2. 验证安装
hexo --version
# 应该显示：
# hexo: 8.1.1
# hexo-cli: 5.0.0
# 其他依赖版本...

# 3. 创建博客文件夹（可选位置，比如在文档文件夹）
cd ~/Documents
hexo init myblog
cd myblog

# 4. 安装 Hexo 依赖
npm install

# 5. 验证 Hexo 运行
hexo clean
hexo generate
hexo server
# 打开浏览器访问：http://localhost:4000

8. 安装和配置 Butterfly 主题

1
2
3
4
5
6
7
8
9
10
11
12
13
# 进入 Hexo 博客目录
cd myblog

# 1. 安装 Butterfly 主题
npm install hexo-theme-butterfly@latest

# 2. 修改主题配置
# 复制默认配置文件
cp node_modules/hexo-theme-butterfly/_config.yml _config.butterfly.yml

# 3. 修改根目录的 _config.yml
# 使用 VSCode 编辑：
code _config.yml
1
2
3
4
5
6
7
8
9
# _config.yml 中修改：
theme: butterfly

# 其他建议配置：
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: false
  trailing_html: false

9. 创建 GitHub 仓库

  1. 登录 GitHub：https://github.com

  2. 创建新仓库

    • 点击右上角 “+” → “New repository”
    • 仓库名：your-blog-name
    • 描述：可选
    • 选择：Public（公开）
    • 勾选：Add a README file
    • 点击 “Create repository”

  3. 本地配置远程仓库

1
2
3
4
5
6
7
8
9
10
11
# 进入博客目录
cd myblog

# 初始化 Git 仓库
git init

# 添加远程仓库
git remote add origin https://github.com/你的用户名/你的仓库名.git

# 创建 .gitignore 文件
code .gitignore
1
2
3
4
5
6
7
8
9
# .gitignore 内容：
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
_multiconfig.yml

10. 创建 Hexo 部署配置

1
2
3
4
5
# 1. 安装 hexo-deployer-git
npm install hexo-deployer-git --save

# 2. 配置部署设置
code _config.yml
1
2
3
4
5
6
# 在 _config.yml 末尾添加：
deploy:
  type: git
  repo: https://github.com/你的用户名/你的仓库名.git
  branch: main
  message: "站点更新: {{ now('YYYY-MM-DD HH:mm:ss') }}"

11. 创建第一个博客文章

1
2
3
4
5
# 创建新文章
hexo new "我的第一篇博客"

# 编辑文章
code source/_posts/我的第一篇博客.md
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
# 示例文章内容
---
title: 我的第一篇博客
date: 2024-01-15 14:00:00
tags:
  - 博客
  - Hexo
categories:
  - 教程
---
## 欢迎来到我的博客！

这是我的第一篇博客，使用 Hexo 和 Butterfly 主题构建。

<!-- more -->

## 功能特点
- 🚀 快速生成静态页面
- 🎨 美观的 Butterfly 主题
- 📱 响应式设计
- 🔍 SEO 友好

## 后续计划
1. 添加评论系统
2. 配置统计工具
3. 优化加载速度

12. 本地测试

1
2
3
4
5
6
7
8
9
10
# 1. 生成静态文件
hexo clean && hexo generate

# 2. 启动本地服务器
hexo server

# 3. 在浏览器访问：
# http://localhost:4000

# 4. 检查主题是否正确加载

13. 部署到 GitHub

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 提交所有更改
git add .
git commit -m "初始化Hexo博客"

# 2. 推送到 GitHub
git push -u origin main

# 3. 使用 Hexo 部署
hexo deploy

# 4. 访问 GitHub Pages（如果启用）
# https://你的用户名.github.io/你的仓库名

14. VSCode 配置优化

创建 .vscode/settings.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "files.associations": {
        "*.yml": "yaml"
    },
    "editor.wordWrap": "on",
    "editor.fontSize": 14,
    "workbench.colorTheme": "GitHub Dark",
    "markdown.preview.fontSize": 14,
    "terminal.integrated.fontSize": 13,
    "git.autofetch": true,
    "git.confirmSync": false
}

15. 创建快捷脚本

在博客根目录创建 deploy.ps1：

1
2
3
4
5
6
7
8
9
# deploy.ps1
Write-Host "开始部署..." -ForegroundColor Green
hexo clean
hexo generate
hexo deploy
git add .
git commit -m "更新: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
git push origin main
Write-Host "部署完成!" -ForegroundColor Green

设置执行权限：

1
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

16. 验证完整环境

运行验证脚本：

1
2
3
4
5
6
7
8
9
10
# 创建 verify.ps1
@"
验证环境配置：
1. PowerShell 版本: $($PSVersionTable.PSVersion)
2. Git 版本: $(git --version 2>$null)
3. Node.js 版本: $(node --version)
4. npm 版本: $(npm --version)
5. Hexo 版本: $(hexo --version | Select-Object -First 1)
6. VSCode 版本: $(code --version 2>$null | Select-Object -First 1)
"@ | Write-Host

🚀 故障排除

常见问题解决：

  1. 权限问题
1
2
3
4
# 以管理员身份运行 PowerShell
# 修复 npm 权限
npm cache clean --force
npm install -g npm@latest
  1. 端口占用
1
2
3
4
# 检查端口占用
netstat -ano | findstr :4000
# 终止进程
taskkill /PID 进程号 /F
  1. Hexo 命令找不到
1
2
3
4
5
# 重新安装 hexo-cli
npm uninstall -g hexo-cli
npm install -g hexo-cli@8.1.1
# 添加到 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\你的用户名\AppData\Roaming\npm", "User")
  1. Git 提交失败
1
2
3
# 重置 Git 凭证
git config --global --unset credential.helper
git config --global credential.helper manager