Hexo建站指南

发表于 2025-04-06 更新于 2025-04-11 分类于建站指南阅读次数：本文字数： 6.8k 阅读时长 ≈ 17 分钟

Hexo建站全流程+问题分析，让小白也能打造属于自己的Hexo个人博客网站！

作为一名电脑小白，如何打造属于自己的个人博客网站呢？

在这个流程中，我们将会学会Hexo建站的基本流程，即使是电脑小白也能轻易上手！

在此，我将以win11系统的家庭中文版为例，帮助大家打造属于自己的网站！

Hexo为Hexo的中文官方文档

为什么选择Hexo?

核心优势：

部署难度低：静态网站生成器，无需数据库，支持GitHub Pages免费托管
主题生态丰富：支持Markdown写作与插件扩展（如SEO优化、评论系统），提供开箱即用的美观界面和交互功能（如评论系统、音乐播放器）
生态规模：生态规模主题超500个，插件超1000个，中文社区活跃度高，部署教程完善（尤其适合国内开发者）
交互功能优秀：支持第三方评论系统
扩展性优良：插件生态成熟
Markdown 写作友好：支持通过 hexo new 命令快速创建文章，结合 Typora 等编辑器实现“写作-发布”无缝衔接，降低非技术用户的迁移成本。
前端技术栈适配：开发者可通过 JavaScript 快速定制主题或开发插件（如集成 Algolia 搜索）

Hexo 在个人博客场景的专注设计、中文社区的强支撑以及开箱即用的易用性使其成为综合最优解。对于追求「快速搭建」和「高颜值」的个人用户，Hexo 的生态成熟度与学习曲线平滑度远超同类工具。

环境准备

安装Node.js

访问Node.js官网，下载LTS版本（长期支持版），双击安装后打开终端输入node -v显示版本号即成功
注意：安装时会自动包含npm包管理器，无需单独安装

安装Git

访问Git官网，下载Windows版，安装时所有选项保持默认，完成后在终端输入 git --version 验证

在这里，我们默认用户可以根据官方文档进行Node.js以及Git的安装，在环境准备方面不做过多的赘述

Hexo初始化（本地搭建）

全局安装Hexo 在任意文件夹空白处右键选择「Git Bash Here」，输入：
1
npm install -g hexo-cli #安装Hexo核心工具
在这里，我在D盘上创建了Projects文件夹，从而在Projects的Git Bash上进行的操作

PS：我们通过快捷键Shift+鼠标右键可以直接进行“显示更多选项“的操作，从而点开Open Git Bash here选项卡进行操作

’#’号后面为注释，不要输入，之后的代码也一样

创建博客文件夹

1
2
3

hexo init myblog  # 创建名为myblog的文件夹
cd myblog         # 进入该文件夹
npm install       # 安装依赖（约1分钟）

本地预览

1
2
3

hexo clean   # 清理缓存
hexo g       # 生成静态文件
hexo s       # 启动本地服务器

浏览器打开 http://localhost:4000 即可看到默认博客页面

部署到GitHub（免费托管）

创建GitHub仓库

登录GitHub，新建仓库 用户名.github.io（如用户名为Tom则填Tom.github.io），其他选项保持默认

PS: GitHub Pages 的 主站点服务（即通过 https://用户名.github.io 直接访问的网站）必须使用固定仓库名 用户名.github.io，无法自定义。这是 GitHub Pages 的底层规则限制

配置Hexo部署 用记事本打开 myblog/_config.yml 文件，在末尾添加:
1
2
3
4
deploy:
type: git
repo: https://github.com/你的用户名/你的用户名.github.io.git
branch: main
PS: 每个冒号后必须加空格！否则报错

PS: 注意把代码中你的用户名这一项改为你的Github用户名，不要直接复制粘贴整段代码

安装部署插件并上传

1 2	npm install hexo-deployer-git --save # 安装插件 hexo clean && hexo g -d # 一键部署到GitHub

完成后访问 https://你的用户名.github.io 即可看到线上博客

基础配置（个性化修改）

编辑站点配置文件

编辑_config.yml 中的以下字段：

title: 博客标题
subtitle: 副标题
author: 显示名称（与Github一致）
description: 网站简介
author: 你的名字
language: zh-CN  # 中文界面
url: 你的Github Pages地址（即你的GitHub仓库地址，格式为https://你的Github用户名.github.io）
delpoy: 
   type: git
   repo: [email protected]:你的Github用户名/你的Github用户名.github.io.git # 仓库SSH地址
   branch: main #Github默认主分支

PS: 注意个性化修改，不要照搬照抄

repo字段需替换为你的仓库SSH地址（可在GitHub仓库页点击“Code” → “SSH”获取）

本地预览博客

启动本地服务器
1
hexo server

访问http://localhost:4000查看本地效果

创建第一篇测试文章
1
hexo new "我的第一篇博客"

文章会生成在 source/_posts/我的第一篇博客.md，用Markdown语法编辑内容后保存

部署到Github Pages

生成静态文件并部署

1
2
3

hexo clean   # 清除缓存
hexo generate  # 生成静态文件（可简写为 hexo g）
hexo deploy   # 部署到GitHub（可简写为 hexo d）

首次部署需输入GitHub账号密码或配置SSH密钥

访问在线博客 稍等2分钟后，访问 https://你的用户名.github.io 即可看到你的博客。

常见问题

GitHub未正确识别SSH密钥，导致部署权限被拒绝（Permission denied (publickey)）

解决方案：
1. 检查并生成SSH密钥
  - 步骤1：生成SSH密钥 打开Git Bash，执行以下命令（替换为你的GitHub邮箱）：
    1
    ssh-keygen -t rsa -C "你的Github用户名@github.com"
    连续按3次回车（不设密码），密钥会生成在 ~/.ssh/ 目录下
  - 步骤2：添加公钥到GitHub
    - 复制公钥内容
      1
      cat ~/.ssh/id_rsa.pub
    - 登录GitHub → Settings → SSH and GPG Keys → New SSH Key → 粘贴公钥
  - 步骤3：测试SSH连接
    
    执行以下命令，若返回 Hi 你的Github用户名! 表示成功：
    1
    ssh -T git@github.com
2. 修正Hexo配置文件
  - 检查 _config.yml 的仓库地址 确保 repo 字段使用 SSH协议（而非HTTPS）：
    1
    2
    3
    4
    deploy:
    type: git
    repo: [email protected]:vigilux418/vigilux418.github.io.git # 必须是SSH格式
    branch: main
    ⚠️ 如果之前使用HTTPS地址，需修改为SSH格式
3. 清除缓存并重新部署
  - 删除 .deploy_git 文件夹 该文件夹可能包含旧缓存导致冲突：
    1
    rm -rf .deploy_git
  - 重新生成并部署
    1
    2
    3
    hexo clean
    hexo g
    hexo d
4. 检查Git全局配置
  - 设置Git用户名和邮箱（与GitHub一致）
    1
    2
    git config --global user.name "你的Github用户名"
    git config --global user.email "你的Github用户名@github.com"
5. 密钥权限处理
  
  Windows/Mac需确保私钥文件权限为 600：
  1
  chmod 600 ~/.ssh/id_rsa
6. LF/CRLF警告处理
  
  日志中的 LF will be replaced by CRLF 是Git换行符警告，不影响部署。如需解决：
  1
  git config --global core.autocrlf false # 关闭自动转换
国内网络环境对Github访问限制/代理配置异常

可以通过修改系统hosts文件来绕过默认的DNS流程

缺点：1. IP时效性：GitHub的IP可能变动，建议定期更新hosts内容（可订阅GitHub520项目自动更新）
1. 防病毒误删：部分杀毒软件可能拦截hosts修改，操作前可临时关闭防护
推荐方案：使用代理工具

笔者使用代理工具为Clash for Windows（具体安装情自行搜索）

设置HTTP/HTTPS代理

配置命令：
1
2
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
端口号：Clash默认端口为7890（若修改过需同步调整）
验证与测试
1. 检查代理连通性
  - 测试命令：
    1
    curl -v https://github.com
    若返回HTTP/2 200表示代理生效
2. 克隆主题仓库
  - 执行命令：
    1
    git clone https://github.com/next-theme/hexo-theme-next.git themes/next
    成功克隆即表示配置正确

更换主题（可选）

推荐使用NexT主题

下载主题

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

启用主题

修改 _config.yml：
1
theme: next
主题配置参考路径 themes/next/_config.yml（需自行调整导航栏、配色等）

重启服务即可生效

编辑博客文章

创建/打开文章

创建文章

在博客根目录（比如我的是D:\Projects\myblog）打开Git Bash，输入以下命令：
1
hexo new "我的第二篇博客"
此命令会在 source/_posts 目录生成 我的第二篇博客.md 文件
打开文章

在博客根目录的source文件夹中找到.md文件，双击打开（推荐使用VS Code或Typora编辑）

编辑Markdown内容

在文件头部添加YAML格式的元信息，例如：
1
2
3
4
5
6
title: 我的第二篇博客
date: 2025-04-04 14:30:00
tags:
- 技术
- Hexo教程
categories: 建站指南
tags 和 categories 用于分类和标签页生成

编写正文

使用Markdown语法撰写内容，支持代码块、图片插入等：

1
2
3

## 欢迎阅读我的第二篇博客
这是正文内容，支持**加粗**、*斜体*、[链接](https://example.com)等格式。
![图片描述](/images/example.jpg)  # 图片需放在`source/images`目录

注意将图片放入source/images文件夹

source文件夹指的是根目录下的source文件夹，而非其它目录下的source文件夹

如果你的source/images文件夹不存在，你需要去自己创建一个文件夹 ### 本地预览博客

启动本地根服务器

在博客根目录（比如我的是D:\Projects\myblog）执行：
1
hexo clean && hexo generate && hexo server

作用：清除缓存 → 生成静态文件 → 启动本地服务
访问地址：浏览器输入 http://localhost:4000 实时查看效果

部署更新到线上博客

生成静态文件

1	hexo generate # 或简写为 hexo g

生成的文件会存储在 public 目录，包含HTML、CSS等资源

部署到GitHub Pages

1	hexo deploy # 或简写为 hexo d

前提：确保 _config.yml 中已正确配置Git仓库地址和分支

验证：等待2分钟后访问 https://你的Github用户名.github.io 查看更新

访问我的博客

通过GitHub Pages默认链接访问
- 链接格式：https://你的Github用户名.github.io > 假设你已经正确配置仓库
自定义域名访问（可选）

步骤：

购买域名：在阿里云、腾讯云等平台注册（如example.com）。
配置DNS解析：添加CNAME记录指向你的Github用户名.github.io
设置GitHub Pages：
- 在博客根目录创建CNAME文件，内容为你的域名（如blog.example.com）。
- 推送到GitHub仓库后，在仓库的Settings > Pages中绑定域名
自定义域名访问不会操作不用担心，我们将手把手教你绑定

自定义域名访问

以下是以阿里云为例的自定义域名配置全流程，用最简单的方式手把手教你操作，无需技术基础：

第一步：购买域名

注册阿里云账号
- 访问阿里云官网 → 点击右上角【注册】→ 填写信息并完成实名认证
搜索并购买域名
- 登录后进入【域名注册】页面 → 输入想要的域名（如 example.com）→ 选择未被占用的域名 → 加入购物车并付款

较便宜的域：.top、.site、.fun、online

第二步：配置DNS解析（关键步骤）

目标：让域名指向你的GitHub Pages网站

进入阿里云域名控制台
- 登录阿里云 → 点击顶部菜单【控制台】→ 左侧导航栏选择【域名】→ 找到已购买的域名 → 点击【解析】
添加A记录（顶级域名解析）
- 适用场景：直接使用 example.com 访问博客。
- 操作步骤：
  - 点击【添加记录】→ 填写以下信息：
    - 主机记录：@ （代表顶级域名）
    - 记录类型：A
    - 记录值：依次添加GitHub的4个IP地址:
      1
      2
      3
      4
      185.199.108.153
      185.199.109.153
      185.199.110.153
      185.199.111.153
      重复操作：共需添加4条A记录，每条填一个IP地址
    - TTL：默认10分钟
添加CNAME记录（子域名解析，可选）
- 适用场景：使用 www.example.com 访问博客。
- 操作步骤：
  - 点击【添加记录】→ 填写：
    - 主机记录：www
    - 记录类型：CNAME
    - 记录值：填你的GitHub Pages地址（即 你的Github用户名.github.io）
    - TTL：默认10分钟
保存设置
- 点击【确认】→ 等待生效（通常10分钟~48小时）

第三步：在GitHub仓库设置域名

创建CNAME文件
- 在本地博客根目录（如 D:\Projects\myblog）新建文件 CNAME（无后缀）→ 内容填你的域名（如 example.com）→ 保存
常见问题：弹窗提醒“…”

原因：1. 隐藏的文件后缀未删除

Windows默认隐藏文件扩展名（如.txt），若直接重命名文件为CNAME，实际文件名可能是CNAME.txt，系统会因后缀与内容不匹配报错
1. 系统无法直接修改
终极解决方案：
1. 打开命令提示符
  - 在D:\Projects\myblog目录的地址栏输入cmd → 回车。
2. 执行创建命令
  1
  echo example.com > CNAME
  - 此命令会直接生成无后缀的CNAME文件，内容为你的域名（替换example.com）。
验证文件是否正确
1. 检查文件图标
  - 正确的CNAME文件应显示为“未知类型”图标（非记事本图标）。
2. 查看文件属性
  - 右键文件 → 【属性】→ 确认“类型”为文件而非文本文档。
3. 推送至GitHub测试
  - 执行git add CNAME和git push后，检查GitHub仓库根目录是否出现该文件。
推送文件到GitHub
1
2
3
git add CNAME
git commit -m "添加域名配置"
git push
常见问题：出现报错fatal: not a git repository

原因：当前目录未初始化 Git 仓库，或者 未正确进入 Git 仓库的根目录
1. myblog 目录下没有 .git 文件夹（即从未执行过 git init）
2. 当前路径与 Git 仓库的实际路径不匹配（例如误入子目录或父目录）
解决方案：

初始化 Git 仓库
1. 确认当前路径 在 Git Bash 中输入以下命令，检查是否在 myblog 目录：
  1
  pwd # 应输出正确的根目录
  如果路径错误，使用 cd 命令切换目录：
  1
  cd /d/Projects/myblog # 注意将路径替换为你的博客根目录！这个是我的博客根目录！
2. 初始化仓库 执行以下命令创建 Git 仓库：
  1
  git init
3. 验证仓库状态
  1
  git status # 应显示 "No commits yet" 或文件列表
  如果成功，继续执行 git add CNAME 即可。
常见问题：fatal: No configured push destination

原因：本地 Git 仓库尚未关联远程仓库（如 GitHub 仓库）
1. 未配置远程仓库地址 本地仓库的 .git/config 文件中缺少 [remote "origin"] 配置项，Git 不知道要将代码推送到哪个远程服务器
2. 首次推送未指定目标 首次推送代码时，必须明确告知 Git 远程仓库的 URL 或已配置的远程仓库名称
解决方案：
1. 步骤 1：关联远程仓库
  
  在 Git Bash 中执行以下命令，将本地仓库与 GitHub 仓库关联（替换 你的GitHub仓库URL）：
  1
  git remote add origin https://github.com/你的用户名/你的仓库名.git
  - origin 是远程仓库的默认别名，可自定义（如 github）。
2. 步骤 2：验证远程配置
  
  输入以下命令检查是否关联成功：
  1
  git remote -v
3. 预期输出：
  1
  2
  origin https://github.com/你的电脑名/myblog.git (fetch)
  origin https://github.com/你的电脑名/myblog.git (push)
4. 步骤 3：推送代码到远程仓库
  
  执行推送命令
  1
  git push -u origin main
  参数说明：
  - -u：将本地分支与远程分支关联，后续可直接用git push
  - origin：远程仓库别名。
  - main：分支名称（默认主分支）。
若你发现你不慎写错了origin，可以用以下命令替换或更新origin:
1
git remote set-url origin 新仓库URL
常见问题： git push 被拒绝

原因：本地仓库的提交历史与远程仓库不一致
- 远程仓库存在本地没有的新提交（比如通过网页直接修改、其他设备推送过代码，或初始仓库有默认文件），而 Git 为防止数据丢失拒绝覆盖。
解决方案：
1. 方法一：
  1. 拉取远程代码：
    1
    git pull origin main
    - 若拉取后无冲突，Git 会自动合并并生成一条合并提交记录。
  2. 重新推送：
    1
    git push origin main
2. 若方案一无法解决，使用方案二（使用变基合并（保证提交历史线性））：
  
  若不想生成合并提交记录，可用 --rebase 参数将本地提交“嫁接”到远程最新提交上：
  1
  2
  git pull --rebase origin main # 拉取并变基
  git push origin main # 重新推送
  - 适用场景：希望提交历史保持整洁（如个人项目）。
绑定域名到GitHub Pages
- 打开GitHub仓库 → 【Settings】→ 左侧【Pages】→ 在【Custom domain】输入你的域名（如 example.com）→ 点击【Save】

第四步：启用HTTPS（安全访问）

强制HTTPS
- 在GitHub Pages设置页面 → 勾选【Enforce HTTPS】→ 等待约5分钟（证书自动颁发）
验证成功
- 浏览器访问 https://example.com → 地址栏显示绿色锁图标即成功

第五步：验证是否生效

检查DNS解析
- 打开DNS检测工具 → 输入域名 → 查看是否解析到GitHub IP
访问测试
- 直接输入你的域名（如 example.com）→ 显示博客首页即成功！
常见问题：自定义域名example.com无法访问（显示404），但直接访问你的Github用户名.github.io正常

可能的解决方案：
1. GitHub Pages配置未绑定自定义域名关键验证点：
  1. 检查GitHub仓库设置：
  - 进入仓库 → Settings → Pages → Custom domain 是否填写 example.com。
  - 若未填写，需在此处添加并保存。
  1. CNAME文件验证：
  - 仓库根目录需存在 CNAME 文件，内容为 example.com（无协议头）。
  - 若文件被误删或修改，GitHub Pages会解除域名绑定。
2. DNS解析未生效或错误
  
  排查步骤:
  1. 登录阿里云控制台→ 域名解析DNS→ 检查example.com的解析记录：
    - GitHub Pages要求CNAME解析到<你的GitHub用户名>.github.io
    - 若误设为A记录，需修改为CNAME类型，记录值为GitHub Pages地址。
  2. TTL时间检查：若最近修改过解析记录，需等待TTL过期（通常2-24小时）或手动刷新本地DNS缓存（Windows：ipconfig /flushdns；macOS：sudo killall -HUP mDNSResponder）。
3. HTTPS证书未自动部署
- 现象：若强制HTTPS访问但证书未生效，可能导致404。
- 解决方案：
  1. 在GitHub Pages设置中勾选 Enforce HTTPS。
  2. 若证书未生成（状态为“Pending”），等待10分钟或重新保存CNAME配置触发证书申请。
1. 域名状态异常
  - 潜在问题：
    - 域名未实名认证：阿里云域名需完成实名审核方可解析。
    - 域名过期或冻结：登录阿里云控制台 → 域名管理 → 查看 example 状态。

Hexo博客的更新与修改

升级Hexo与主题

升级Node.js和Hexo

# 升级Node.js到最新LTS版本（需先安装nvm）
nvm install --lts
nvm use --lts

# 升级Hexo到最新版
npm uninstall -g hexo-cli  # 卸载旧版
npm install -g hexo-cli    # 安装新版

更新主题（以Next主题为例）

若主题通过Git安装：

1 2	cd themes/next # 进入主题目录 git pull # 拉取最新代码

若主题通过npm安装：

1	npm update hexo-theme-next # 更新主题包

修改博客基础配置

编辑站点配置文件（_config.yml）

打开根目录的_config.yml，修改以下字段：

# Site
title: 你的博客名
subtitle: "副标题（如：技术分享与生活记录）"
description: "博客简介"
keywords: "关键词1, 关键词2"
author: 你的名字
language: zh-CN  # 中文
timezone: Asia/Shanghai  # 时区

修改主题配置文件

进入主题目录（如themes/next/_config.yml），调整以下设置：

# 头像设置
avatar:
  url: /images/avatar.jpg  # 图片需放在source/images目录
  rounded: true  # 圆形头像
  rotated: true   # 鼠标悬停旋转

# 菜单导航
menu:
  首页: / || fa fa-home
  归档: /archives/ || fa fa-archive
  标签: /tags/ || fa fa-tags
  关于: /about/ || fa fa-user

PS: 在VSCode中，可以用Ctrl+F快捷键，快速查找关键词

调整博客样式

更换主题风格（以Next为例）

在主题配置文件中搜索scheme，选择一种预设风格：
1
scheme: Pisces # 可选Muse/Mist/Pisces/Gemini
自定义CSS样式
1. 在source/_data目录新建styles.styl文件（若无此目录则手动创建）
2. 添加自定义样式（例如修改字体和背景）：
  1
  2
  3
  4
  body {
  font-family: "Microsoft YaHei", sans-serif;
  background: url(/images/bg.jpg);
  }
3. 在主题配置中启用自定义CSS：
  1
  2
  custom_file_path:
  style: source/_data/styles.styl

进阶优化（可选）

添加搜索功能

1	npm install hexo-generator-searchdb --save

在主题配置（themes/_config文件）中启用：

1 2	local_search: enable: true

开启评论系统（以Gitalk为例）

1	npm install gitalk --save

在主题配置文件中添加：

gitalk:
  enable: true
  clientID: "你的GitHub应用ID"
  clientSecret: "你的GitHub应用密钥"
  repo: "你的Github用户名.github.io"
  owner: "你的Github用户名"

清理缓存并重启服务操作

1	hexo clean && hexo g && hexo s

常见问题：

使用http://localhost:4000与http://你的Github用户名.github.io预览结果不一致

常见原因：浏览器缓存干扰

解决方案：
强制刷新线上页面（Ctrl+F5或Shift+刷新）
在Hexi命令链中加入缓存清理
1
hexo clean && hexo g -d