⚙️ 准备工作：你的建站工具箱

在开始前，需要先准备好两个基础软件和一个GitHub账户。

工具 作用 下载/注册地址
Node.js 博客框架 Hexo 的运行环境，就像土壤对于种子一样重要。 nodejs.org（请务必选择 LTS 长期支持版）
Git 版本控制工具，用来将你的博客“推送”到 GitHub 上。 git-scm.com
GitHub 账号 代码和网页的托管平台。 github.com

安装与验证：两个软件安装完成后，建议在终端（macOS/Linux）或命令提示符（Windows）输入 node -v 和 git --version，如果显示出各自的版本号，就说明安装成功了。

Windows 用户请注意：强烈建议你使用 Git Bash（安装 Git 后自带）代替 CMD 或 PowerShell 来执行后续命令，可以避免很多路径和编码上的问题。

网络优化（可选）：如果下载速度慢，可以在终端中运行 npm config set registry https://registry.npmmirror.com，设置淘宝镜像源来加速。

🏠 第一步：在本地搭建你的 Hexo 博客

  1. 安装 Hexo 脚手架：在终端中执行下方命令，全局安装 Hexo 命令行工具：

    bash

    1
    npm install -g hexo-cli

  2. 初始化你的博客：

    • 在电脑上你想存放博客的位置（比如 Documents 文件夹），打开终端，用下面三条命令来初始化一个博客并启动预览服务器。
    • 请将 <folder-name> 替换为你喜欢的博客文件夹名字（如 my-blog），避免使用中文。

    bash

    1
    2
    3
    hexo init <folder-name>
    cd <folder-name>
    npm install

  3. 本地预览：执行下面的命令后，在浏览器访问 http://localhost:4000，就能看到 Hexo 默认的博客界面了！按 Ctrl+C 可以停止服务器。

    bash

    1
    hexo server

博客目录结构：初始化完成后，你的博客文件夹内会生成以下主要目录和文件。

目录/文件 功能描述
_config.yml 博客的主配置文件，几乎所有设置（网站标题、URL、部署信息）都在这里修改。
source/ 你的内容仓库。所有文章（Markdown 文件）、图片、页面（如“关于我”）都放在这里。
themes/ 主题文件夹，用来存放和切换博客的外观主题。
scaffolds/ 模板文件夹，里面定义了新建文章或页面时的默认 Front-matter 结构。

重要提示：生成静态文件（hexo generate 或 hexo g）后出现的 public/ 文件夹，是整个网站的“成品”，需要被推送到 GitHub 上展示。

✍️ 第二步：内容创作与主题美化

文章创作

  1. 新建文章：在博客根目录下打开终端，使用下面命令。Hexo 会自动在 source/_posts/ 目录下生成一个 .md 文件。

    bash

    1
    hexo new "我的第一篇博客"

  2. 认识 Front-matter：用文本编辑器（如 Typora, VS Code）打开这个文件，会看到最上方被 --- 包裹的区域，这就是 Front-matter。它定义了文章的标题、日期、标签等元数据（关于事物的信息），请务必保留并能在此自由修改。

    yaml

    1
    2
    3
    4
    5
    6
    ---
    title: Hello World # 文章标题
    date: 2024-01-01 10:00:00 # 发布日期
    tags: [Hexo, 教程] # 标签
    categories: 技术 # 分类
    ---

  3. 开始用 Markdown 写作：在 --- 分隔线之后，就可以用 Markdown 语法开始书写正文了。

主题美化

Hexo 有大量免费精美的主题，能把你朴素的基础博客变得惊艳。以下是几个广受好评的选择：

  • NexT: 精于心，简于形。优雅经典的双栏布局，功能强大，适合严肃的技术博客。
  • Butterfly: 界面现代美观，拥有丰富的动效和完整的配置项，视觉体验极佳。
  • Fluid: 一款 Material Design 风格的 Hexo 主题，设计简洁、注重性能，配置项丰富。
  • Icarus: 简洁、现代、响应式的设计，配置逻辑清晰。

以安装和启用 NexT 主题为例：

bash

1
2
3
4
5
# 1. 克隆主题到你的博客目录下
git clone https://github.com/theme-next/hexo-theme-next themes/next

# 2. 打开站点根目录下的 _config.yml 文件，找到 theme 字段，修改为 next
theme: next

最佳实践：现在很多主题都支持通过独立的配置文件（如 _config.next.yml）来进行自定义，这样能避免直接修改主题源文件，方便后续升级。

🚀 第三步：将博客部署到 GitHub Pages

这是关键一步，让你的本地博客“上线”成为真正的网站。

1. 在 GitHub 创建专属仓库（Repository）

登录 GitHub，新建一个仓库（New repository）。

⚠️ 命名铁律：仓库名必须是 你的GitHub用户名.github.io。例如，你的用户名是 jack123，仓库名就必须是 jack123.github.io。记住，它是用户名，不是昵称。这关系到你的博客网址能否正常访问。

⚠️ 核心避坑：创建仓库时，绝对不要勾选任何初始化选项，如 “Add a README file”，务必保持空仓库状态，否则后续推送代码会遇到冲突导致失败。

2. 配置部署信息

打开你博客根目录下的 _config.yml 文件，找到 Deploy 部分，修改为以下格式。注意，repo 那行我们推荐用 SSH 链接（git@github.com:...）。记得把 yourname 替换成你自己的用户名。

yaml

1
2
3
4
5
6
7
8
9
10
# URL
url: https://yourname.github.io  # 替换成你的博客地址
root: /
# 其他配置保持不变...

# Deployment
deploy:
  type: git
  repo: git@github.com:yourname/yourname.github.io.git
  branch: main

3. 安装部署插件并执行部署

在博客根目录打开终端，执行以下三条命令：

bash

1
2
3
4
5
6
7
8
# 安装一键部署插件
npm install hexo-deployer-git --save

# 清理并生成静态文件
hexo clean && hexo generate

# 一键部署到 GitHub
hexo deploy

如果是首次部署，系统可能会提示你输入 GitHub 的用户名和密码（或 Token）。

等待部署完成后，访问 https://<你的用户名>.github.io，你的个人博客就正式上线了！之后每次写完新文章，只要再执行 hexo clean && hexo generate && hexo deploy 就能更新网站。

✨ 第四步：进阶配置与实用技巧

1. 绑定独立域名

如果你有自己的域名，可以把它绑定到你的 *.github.io 博客上。

  1. 在 source 文件夹下新建一个名为 CNAME 的文件（注意没有后缀名），里面只写入你的域名，如 www.myblog.com。
  2. 在域名 DNS 管理后台，添加一条 CNAME 记录，将你的域名指向 你的用户名.github.io。

2. 多电脑同步写作

想在不同电脑上管理博客？可以实现。

  1. 备份源码：在 GitHub 的 yourname.github.io 仓库中，新建一个分支（如 hexo），用于存放博客的“源代码”（即除了 public 文件夹以外的所有文件）。
  2. 新电脑操作：在新电脑上 git clone 你存放源码的分支，然后在新目录下执行 npm install 安装依赖，就可以无缝继续创作了。

3. 图片管理

推荐使用图床（专门的图片托管服务）存储图片，然后在 Markdown 里直接引用图片链接，能够保持博客仓库的轻量。

4. 添加评论功能

静态博客本身没有评论功能，但可以方便地集成第三方服务，例如 Gitalk（利用 GitHub Issues 存储评论）或 Waline 等，具体配置可参考所选主题的说明文档。

🔧 常见问题与解决方法 (Q&A)

  • Q: 为什么 hexo deploy 后，访问网站是 404？

    • A: 首先检查 GitHub 仓库名是否正确（必须是 用户名.github.io）。然后进入仓库的 Settings -> Pages，查看部署分支是否选为 main 且目录为 /(root)。如果一切正常，你的代码可能还没推送成功。

  • Q: 部署时遇到报错 “ERROR Deployer not found: git”

    • A: 这是因为你还没安装部署插件。在博客目录下，运行以下命令再重新部署即可。

    bash

    1
    npm install hexo-deployer-git --save

  • Q: 配置文件中 type: 后面没有空格，导致报错怎么办？

    • A: YAML 语法十分敏感，冒号后面必须有一个英文空格。请仔细检查。

  • Q: 本地预览正常，部署后样式或功能丢失怎么办？

    • A: 这通常是路径问题。
    • 确保 _config.yml 中的 url 和 root 配置正确。如果部署到的是用户站点（用户名.github.io），root 应为 /。
    • 如果部署到的是项目站点（用户名.github.io/项目名），则 root 应为 /项目名/。