从零搭建Hexo静态博客：Git、Node.js与GitHub Pages实战指南

1. 项目概述：为什么现在还要自己搭博客？

在信息流和社交媒体平台泛滥的今天，你可能会问：为什么还要费劲自己搭建一个博客？直接发在公众号、知乎或者小红书不香吗？作为一个从WordPress时代一路折腾过来的老博主，我的答案是：“拥有感”和“自由度”，这两点是任何平台都无法给予的。自己搭建的博客，是你的数字自留地，内容完全由你掌控，没有算法推荐干扰，没有随时可能变更的平台规则，更不用担心哪天账号被封导致所有心血付之东流。它就像你在互联网上买下的一块地，盖起的房子，一砖一瓦都由你设计。

而“从零开始”听起来很吓人，仿佛需要精通服务器、数据库、前端后端。但得益于现代静态站点生成器的成熟，这个过程已经变得异常简单。我们这次要用的Hexo，就是一个基于 Node.js 的、高效快速的静态博客框架。你只需要会一点 Markdown 语法来写文章，剩下的“盖房子”工作——生成网页、处理样式、部署上线——Hexo 都能帮你自动化完成。最终，你的博客会是一套纯粹的 HTML、CSS、JavaScript 文件，可以免费部署在 GitHub Pages、Vercel 等托管服务上，访问速度快，且几乎零成本。

所以，无论你是想记录技术学习心得、分享生活感悟，还是打造个人品牌，一个独立博客都是最好的起点。这篇教程，我将带你用最主流、最稳定的工具链（Git + Node.js + Hexo），一步步走完从本地环境搭建到博客上线发布的完整流程，过程中我会穿插我踩过的所有坑和总结的最佳实践，确保你一次成功。

2. 核心工具链解析：Git、Node.js与Hexo的角色

在动手之前，我们得先搞清楚手里的“工具”都是干什么的。这不是枯燥的理论课，理解它们能让你在出问题时知道该从哪里排查。

2.1 Git：你的时光机和协作伙伴

Git 远不止是“用来下载代码的”。你可以把它理解为一个超级强大的版本控制器和内容同步工具。

• 版本控制：写博客时，你可能会频繁修改主题配置、调整文章样式。Git 可以记录每一次文件的改动。如果你改乱了某个配置，可以轻松回退到之前能正常工作的版本，就像拥有了一个时光机。这对独自维护项目来说简直是救命稻草。
• 内容同步与部署：我们将使用 GitHub 来托管博客源码和生成的静态网页。本地写好文章、生成网站后，通过 Git 命令就能将代码“推送”到 GitHub 的仓库里。GitHub Pages 服务会自动识别这个仓库，并将其中的网页文件发布到互联网上，形成你的博客网站。同时，你在任何一台新电脑上，只需要“克隆”这个仓库，就能立刻获得全部博客内容和环境，无缝继续写作。
• 实操关联：后续的git init,git add,git commit,git push这些命令，都是在完成“本地存档”和“云端同步”这两件核心事。

注意：很多新手会在 Git 配置环节卡住，主要是用户名和邮箱设置不对，导致提交记录作者信息混乱。务必在安装后首先配置全局信息。

2.2 Node.js 与 npm：博客引擎的运行时和零件库

Node.js 是一个 JavaScript 运行时环境。简单类比：就像你的电脑需要安装“Java运行环境”才能运行某些Java软件一样，Hexo 这个程序是用 JavaScript 写的，所以需要 Node.js 环境才能运行。

npm 是随 Node.js 一同安装的包管理器。Hexo 本身功能是核心，但很多扩展功能（比如支持 RSS 生成、文章加密、搜索功能）都是以“零件”（我们称之为“包”或“插件”）的形式存在的。npm 就是帮你从网上（npm仓库）自动下载、安装和管理这些“零件”的工具。

• 版本选择避坑：这是新手最大的坑！Hexo 对 Node.js 版本有要求，并非越新越好。根据官方文档，推荐使用Node.js 18 或 20 的长期支持版本。版本过高可能导致某些插件不兼容。安装 Node.js 时，建议从官网下载 LTS 版本。安装完成后，在命令行输入node -v和npm -v来验证是否安装成功及查看版本。

2.3 Hexo：静态站点生成器，你的博客工厂

Hexo 是我们整个项目的核心。它的工作模式非常清晰：

1. 输入：你写在source/_posts/目录下的 Markdown 文件（你的文章），以及_config.yml这个站点配置文件。
2. 处理：Hexo 读取这些 Markdown 和配置，根据你选定的“主题”的模板，进行渲染。
3. 输出：在public文件夹里生成一整套完整的、静态的 HTML 网站文件。

这个过程是“静态”的，意味着服务器每次访问时不需要像 WordPress 那样动态查询数据库、组装页面，因此速度极快，安全性也极高（因为没有动态脚本执行漏洞）。你本地写好，运行hexo generate命令生成网站，再用hexo deploy部署，读者看到的就是最终结果。

3. 本地环境搭建与初始化实战

理论清楚了，我们开始动手。请严格按照步骤操作，我会指出每个步骤的关键点。

3.1 第一步：安装 Git 并完成基础配置

1. 下载安装：访问 Git 官网，下载对应你操作系统（Windows/macOS/Linux）的安装程序。Windows 用户一路“Next”即可，安装时注意勾选“Git Bash Here”选项，这样以后在文件夹里右键就能直接打开 Git 命令行，非常方便。
2. 基础配置（必须做）：安装完成后，在任意地方右键选择“Git Bash Here”打开命令行窗口，执行以下命令，设置你的全局身份。这个信息会记录在你的每一次提交中。

   git config --global user.name "你的用户名" git config --global user.email "你的邮箱"

   例如：git config --global user.name "zhangsan"，git config --global user.email "zhangsan@example.com"。这个邮箱最好和你后续注册 GitHub 的邮箱一致。
3. 检查安装：输入git --version，如果显示版本号（如git version 2.40.1），说明安装成功。

3.2 第二步：安装 Node.js 和 npm

1. 下载安装：访问 Node.js 官网，下载LTS版本（长期支持版，目前通常是 Node.js 20.x）。同样是一路下一步安装。安装程序会自动将 Node.js 和 npm 添加到系统路径。
2. 验证与版本管理提示：安装完成后，打开一个新的命令行窗口（CMD 或 PowerShell，或者新的 Git Bash），输入：

   node -v npm -v

   应该分别显示 Node.js 和 npm 的版本号。如果这里报错“不是内部或外部命令”，说明环境变量未生效，重启电脑通常可以解决。
3. 配置 npm 镜像源（国内用户必做）：npm 默认源在国外，下载包速度很慢。我们需要将其切换到国内镜像，如淘宝源。

   npm config set registry https://registry.npmmirror.com/

   执行后，可以通过npm config get registry命令检查是否设置成功。

3.3 第三步：安装 Hexo 并初始化博客项目

1. 全局安装 Hexo 命令行工具：在命令行中执行以下命令。-g代表全局安装，这样你可以在任何目录下使用hexo命令。

   npm install -g hexo-cli

   安装完成后，输入hexo -v检查，会打印出 Hexo 及相关依赖的版本信息。
2. 初始化博客文件夹：找一个你喜欢的目录（例如D:\Projects），在命令行中进入该目录，然后执行：

   hexo init myblog

   这个命令会创建一个名为myblog的文件夹，并自动在里面生成博客所需的全部基础文件。cd myblog进入这个文件夹，这是你未来所有操作的“工作目录”。
3. 安装项目依赖：Hexo init 已经安装了一些基础包，但为了确保完整，可以运行：

   npm install

   这会根据package.json文件里的记录，安装所有必要的依赖包到本地的node_modules文件夹。

3.4 第四步：本地启动，看到你的第一个博客

在myblog目录下，执行以下命令：

hexo clean && hexo generate && hexo server

让我解释一下这个组合命令：

• hexo clean：清理之前生成的文件（public文件夹），避免缓存干扰。
• hexo generate（可简写为hexo g）：根据你的源文件生成静态网站到public目录。
• hexo server（可简写为hexo s）：启动一个本地开发服务器，预览你的博客。

执行后，命令行会显示Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.。打开你的浏览器，访问http://localhost:4000，你就能看到默认的 Hexo 博客界面了！恭喜，本地环境搭建成功。

4. 博客核心配置与主题应用详解

现在你看到的是 Hexo 自带的默认主题 “landscape”。接下来，我们要把它变得独一无二。

4.1 站点配置：_config.yml文件解读

在博客根目录下，有一个名为_config.yml的文件，这是 Hexo 的站点配置文件，控制着博客的全局设置。用记事本或 VS Code 等代码编辑器打开它。我们修改几个关键项：

# Site title: 张三的技术小筑 # 博客标题 subtitle: '记录与分享' # 副标题 description: '一个专注于Web开发与生活随想的个人博客' # 站点描述，对SEO很重要 keywords: 前端， JavaScript， 个人博客 # 关键词 author: 张三 # 作者名 language: zh-CN # 语言，设为中文 timezone: 'Asia/Shanghai' # 时区 # URL url: https://yourusername.github.io # 填写你未来博客的在线地址 root: / permalink: :year/:month/:day/:title/ # 文章永久链接格式，这里按年月日+标题

重要提醒：YAML 文件对格式非常敏感！修改时务必注意：

• 冒号:后面必须跟一个空格。
• 使用两个空格进行缩进，不要使用 Tab 键。
• 每一级配置的缩进要一致。

4.2 主题安装与配置：打造高颜值博客

主题决定了博客的外观和布局。Hexo 有海量的社区主题可供选择。我们以目前非常流行、文档齐全的Fluid主题为例。

1. 安装主题：在博客根目录下，运行以下命令。这会将 Fluid 主题下载到themes/fluid文件夹。

   npm install --save hexo-theme-fluid

2. 指定主题：打开根目录的_config.yml，找到theme配置项，将其修改为：

   theme: fluid

3. 创建主题配置文件：Fluid 主题有自己独立的配置文件。你需要将主题提供的示例配置文件复制到博客根目录下并重命名。
   • 首先，在node_modules/hexo-theme-fluid目录中找到_config.yml文件。
   • 将其复制到你的博客根目录（与 Hexo 自己的_config.yml同级）。
   • 将复制过来的文件重命名为_config.fluid.yml。

   实操心得：为什么这么做？Hexo 支持“数据覆盖”。_config.fluid.yml中的配置会覆盖主题包内默认的_config.yml。这样做的好处是，当你将来通过 npm 更新主题时，你的个性化配置不会丢失，因为你的配置在博客根目录下，不会被覆盖。

4. 配置主题：现在打开_config.fluid.yml，你可以进行深度定制。例如：
   • 导航栏：在navbar部分添加你的菜单。
   • 首页横幅：在banner部分设置头图。
   • 主题颜色：在color部分调整配色方案。
   • 页脚信息：在footer部分修改版权信息。 每次修改主题配置后，需要重启本地服务器（Ctrl+C停止，再执行hexo s）才能看到效果。

4.3 写作与发布你的第一篇文章

1. 创建新文章：在博客根目录下运行命令：

   hexo new "我的第一篇文章"

   这会在source/_posts目录下创建一个名为我的第一篇文章.md的文件。
2. 编辑文章：用编辑器打开这个.md文件。文件开头是“Front-matter”，用于设置文章属性，采用 YAML 格式。

   --- title: 我的第一篇文章 date: 2024-05-27 14:00:00 tags: [Hexo, 教程] categories: 建站 ---

   • title: 文章标题。
   • date: 发布时间，可以修改。
   • tags: 标签，多个标签用数组形式[标签1, 标签2]。
   • categories: 分类，可以是字符串或数组（表示多级分类，如[建站, Hexo]）。 Front-matter 下方，就可以用 Markdown 语法愉快地书写正文了。
3. 预览：保存文件后，回到浏览器localhost:4000刷新页面，你就能看到新文章出现在列表中了。Hexo 服务器支持热更新，对于文章内容的修改，通常刷新即可看到；但如果是修改了配置或新建了文章，可能需要重启服务器或重新生成。

5. 部署到 GitHub Pages：让全世界看到你的博客

本地博客再好，也只能自己看。部署到 GitHub Pages，就能获得一个yourusername.github.io的免费域名，全球可访问。

5.1 第一步：创建 GitHub 仓库并配置 SSH 密钥

1. 注册 GitHub：如果你没有账号，先去 GitHub 官网注册。
2. 创建仓库：登录后，点击右上角“+”号，选择“New repository”。仓库名必须严格遵守格式：你的用户名.github.io。例如，你的用户名是zhangsan，那么仓库名就是zhangsan.github.io。将仓库设为 Public（公开），然后创建。
3. 生成 SSH 密钥（关键步骤）：为了让本地 Git 能安全地推送代码到 GitHub，需要配置 SSH 密钥。
   • 打开 Git Bash，输入：

     ssh-keygen -t rsa -C "你的邮箱"

   • 连续按三次回车，接受默认设置。这会在C:\Users\你的用户名\.ssh（Windows）或~/.ssh（macOS/Linux）目录下生成两个文件：id_rsa（私钥，保密）和id_rsa.pub（公钥）。
   • 用记事本打开id_rsa.pub文件，复制里面的全部内容。
4. 在 GitHub 添加公钥：进入 GitHub 设置页面，找到“SSH and GPG keys”选项，点击“New SSH key”。Title 可以随意填（如“My Laptop”），Key 类型选择“Authentication Key”，然后将刚才复制的公钥内容粘贴进去，保存。

5.2 第二步：安装部署插件并配置 Hexo

1. 安装hexo-deployer-git：在博客根目录下运行：

   npm install hexo-deployer-git --save

2. 配置部署信息：打开博客根目录的_config.yml，滚动到最底部，找到deploy部分，修改为：

   deploy: type: git repo: git@github.com:你的用户名/你的用户名.github.io.git # 替换为你的仓库SSH地址 branch: main # 或 master，取决于你的仓库默认分支名 message: Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }} # 可选的提交信息

   重要：repo地址务必使用SSH 格式（即以git@github.com:开头），而不是 HTTPS 格式。这能避免每次部署都要输入密码。

5.3 第三步：执行部署命令

在博客根目录下，执行部署三部曲：

hexo clean && hexo generate && hexo deploy

或者简写为：

hexo clean && hexo g -d

命令执行过程会提示你输入 SSH 密钥的密码（如果你之前设置了的话，默认回车即可）。部署成功后，等待大约1-2分钟，访问https://你的用户名.github.io，你的个人博客就正式上线了！

6. 深度优化、问题排查与进阶技巧

博客上线只是开始，要让其好用、好看，还需要一些优化和问题处理。

6.1 常见问题与解决方案速查表

6.2 进阶优化技巧

1. 自定义域名：如果你有自己的域名（如blog.yourname.com），可以在 GitHub Pages 仓库的 Settings 里设置 Custom domain，并在域名服务商那里添加 CNAME 解析记录指向你的用户名.github.io。别忘了在博客根目录source文件夹下创建一个名为CNAME的文件（无后缀），里面只写一行你的域名。
2. 开启 HTTPS：GitHub Pages 默认支持并强制 HTTPS，确保你的博客连接是安全的。
3. 添加搜索引擎收录：为了让百度、谷歌等搜索引擎收录你的博客，需要生成站点地图。安装插件：

   npm install hexo-generator-sitemap --save npm install hexo-generator-baidu-sitemap --save # 针对百度

   安装后，重新生成部署，访问你的域名/sitemap.xml和你的域名/baidusitemap.xml就能看到地图文件。然后将这些地址提交到各搜索引擎的站长平台。
4. 备份与多端同步：你的整个博客文件夹（除了node_modules和public，因为它们可以通过npm install和hexo g重新生成）就是一个完整的项目。你可以把整个文件夹用 Git 推送到另一个私有仓库（比如叫myblog-source）进行备份。换电脑时，克隆这个源码仓库，运行npm install安装依赖，就能立刻恢复写作环境。
5. 写作流程自动化：你可以编写简单的脚本，将hexo clean && hexo g && hexo d这几条命令整合成一个，比如在根目录创建deploy.sh文件，每次只需运行这个脚本即可完成部署。

6.3 主题选择与个性化建议

除了 Fluid，还有很多优秀的主题，选择时可以考虑：

• Butterfly：功能极其丰富，UI 美观，可定制性极高，社区活跃。
• NexT：经典主题，用户基数大，文档和插件生态非常成熟。
• Stun：设计感强，动画效果出色。
• Icarus：界面简洁，专注于内容展示。

更换主题的步骤大同小异：通过 npm 安装或 Git clone 到 themes 目录，然后在站点配置中修改theme名称即可。深度定制前，务必先阅读该主题的官方文档。

搭建个人博客的过程，就像精心打理一个花园。从最初的荒地（空白文件夹），到打下地基（环境搭建），搭建框架（初始化配置），装修布置（安装主题），再到最终对外开放（部署上线），每一步都充满创造的乐趣。这个博客将完全属于你，它不仅是内容的容器，更是你学习能力、审美品味和技术实践的展示窗。遇到问题别怕，搜索引擎、Hexo官方文档和社区是你最好的老师。现在，开始写下你的第一篇博客吧。