1. 为什么选择 GitHub Pages Hexo 这条路如果你正在看这篇文章大概率是厌倦了在各大平台写博客时被各种广告、审核和格式限制所困扰。想拥有一个完全属于自己的、干净利落的写作空间但又不想在服务器、域名和运维上投入太多金钱和精力。那么GitHub Pages 配合 Hexo 静态博客框架几乎是为你量身定制的方案。我自己的技术博客和几个项目文档站都跑在这套组合上稳定运行了四五年几乎零成本访问速度也完全够用。简单来说GitHub Pages 是 GitHub 提供的免费静态网站托管服务你只需要有一个 GitHub 账号就能获得一个username.github.io的域名和服务器空间。而 Hexo 是一个基于 Node.js 的快速、简洁且高效的博客框架它能把我们用 Markdown 写的文章瞬间转换成漂亮的静态网页。这两者结合意味着你可以在本地用你最顺手的编辑器写文章然后用几条命令就能发布到互联网上整个过程优雅得像在本地保存文件一样自然。这套方案的核心优势在于“静态”。你的网站只是一堆 HTML、CSS、JS 文件没有数据库没有后端逻辑。这带来了极致的安全性和稳定性——几乎没有被黑客攻击的漏洞也几乎不会因为流量突增而宕机。同时它完全免费如果你使用 GitHub 的免费套餐并且天生支持版本控制你的每一篇文章、每一次主题修改都像代码一样被 Git 完整记录随时可以回滚到任意历史版本。网上相关的教程很多但要么过于简略跳过了关键的配置细节让新手卡在某个步骤不知所措要么就是信息陈旧提到的插件或主题已经不再维护。这篇教程我会结合我这些年搭建、维护以及迁移了不下十个 Hexo 博客的经验从最基础的环境安装到深度自定义再到部署和优化手把手带你走通每一个环节并重点分享那些官方文档不会写、但实际操作中一定会遇到的“坑”和技巧。我们的目标是让你看完就能拥有一个既美观又实用的个人博客。2. 环境准备别在第一步就踩坑万事开头难但对于 Hexo 来说开头只要把环境装对后面就一马平川。这里需要的核心是 Node.js 和 Git。2.1 安装 Node.js版本选择有讲究Hexo 运行在 Node.js 环境下。很多教程会直接让你去官网下载最新版但这其实是个潜在的坑。Node.js 的某些新版本可能会与 Hexo 或其插件存在兼容性问题。我的建议是选择长期支持版本。访问 Node.js 官网找到标有LTS的版本进行下载安装。目前以撰写时为例v18.x 或 v20.x 都是稳定的 LTS 版本。安装过程很简单一路“下一步”即可。但请注意安装界面上的一个选项“Automatically install the necessary tools”或类似选项。务必勾选它。这会自动安装npmNode.js 的包管理器以及一些编译工具对于后续安装某些需要本地编译的 Hexo 插件至关重要。安装完成后打开命令行工具Windows 用 Cmd 或 PowerShellMac 用终端。验证安装是否成功node -v npm -v如果两行命令分别输出了版本号如v20.11.0和10.2.4说明安装成功。注意如果你之前安装过旧版本最好先卸载干净再安装新版本避免环境变量冲突。在 Windows 上可以使用专门的卸载工具在 Mac 上如果通过 Homebrew 安装则用brew uninstall node进行卸载。2.2 安装与配置 Git你的内容“时光机”Git 是版本控制工具也是我们连接本地和 GitHub 的桥梁。下载安装前往 Git 官网下载对应系统的安装包。安装时在“Adjusting your PATH environment”这一步建议选择“Git from the command line and also from 3rd-party software”这样可以在任何命令行窗口中使用 Git。关键配置安装完成后需要进行全局配置这关系到你后续提交代码的“身份标识”。git config --global user.name 你的GitHub用户名 git config --global user.email 你的GitHub注册邮箱这个配置非常重要user.name最好和 GitHub 用户名保持一致user.email必须是注册 GitHub 时使用的邮箱。这样你在本地做的每一次提交GitHub 都能正确识别出是你。可选但推荐配置 SSH 密钥。使用 HTTPS 链接每次推送都需要输入账号密码而 SSH 密钥可以实现免密操作更安全便捷。生成密钥ssh-keygen -t rsa -C 你的GitHub注册邮箱一路回车使用默认路径和空密码。查看公钥cat ~/.ssh/id_rsa.pub复制输出的全部内容。登录 GitHub进入Settings - SSH and GPG keys - New SSH key将复制的公钥内容粘贴进去Title 可以自拟如“My Laptop”。2.3 安装 Hexo 脚手架环境就绪后就可以安装 Hexo 的命令行工具了。这个工具能帮你快速创建博客项目骨架。打开命令行执行以下命令进行全局安装npm install -g hexo-cli安装完成后可以通过hexo -v来验证。如果看到 Hexo 的版本信息说明一切顺利。至此所有前置的、底层的工具都已准备完毕。接下来我们将进入激动人心的环节——创建你的第一个博客项目。3. 初始化你的第一个 Hexo 博客项目现在让我们在本地创建一个专属的博客文件夹并让 Hexo 为我们生成初始结构。选择并创建项目目录在你电脑上找一个合适的位置比如D:\Blog或~/Documents/Blog。打开命令行进入这个目录。cd /path/to/your/blog-folder初始化博客执行 Hexo 初始化命令。hexo init my-blog # “my-blog”是你的项目文件夹名可以自定义 cd my-blog这个命令会创建一个名为my-blog的文件夹并在其中下载 Hexo 框架、默认主题landscape和基础配置文件。安装依赖包进入项目文件夹后需要安装项目运行所必需的 Node.js 模块。npm install这个过程会读取package.json文件下载所有列出的依赖。完成后你的博客项目骨架就搭建好了。让我们快速浏览一下生成的关键目录和文件_config.yml站点的核心配置文件博客的名称、描述、URL、部署设置等都在这里。themes/主题目录。默认里面有一个landscape主题。你下载的其他主题也会放在这里。source/源文件目录。你写的 Markdown 文章在_posts/子目录下、关于页、标签页等都在这里。public/这是执行生成命令后Hexo 将 Markdown 转换成的静态 HTML 文件存放处。这个文件夹的内容就是最终要部署到 GitHub Pages 上的。scaffolds/模板文件夹。当你用hexo new命令创建新文章时会依据这里的模板生成文件。本地预览让我们先看看默认博客长什么样。hexo clean # 清除缓存和旧文件 hexo generate # 生成静态文件可简写为 hexo g hexo server # 启动本地服务器可简写为 hexo s执行hexo s后命令行会提示服务已启动通常访问http://localhost:4000就能看到你的博客了这是一个本地预览只有你能看到。你可以试着点击一下感受一下默认主题的样式。至此一个最基础的 Hexo 博客已经在你的本地机器上运行起来了。但这只是开始默认的主题和配置远不能满足个性化需求。接下来我们要对它进行“大改造”。4. 核心配置详解让博客拥有你的DNA_config.yml这个文件是 Hexo 博客的大脑所有全局设置都在这里。直接用文本编辑器打开它推荐使用 VS Code、Sublime Text 等代码编辑器。里面的配置项很多我们聚焦最关键的几个部分。4.1 站点信息配置你是谁你的博客叫什么找到Site部分进行修改title: 我的技术漫谈 # 博客标题 subtitle: 记录、思考与分享 # 副标题 description: 一个专注于后端开发、系统架构与个人成长的博客 # 站点描述对SEO很重要 keywords: 技术,博客,编程,Java,Spring # 关键词用英文逗号分隔 author: 你的名字 # 作者名 language: zh-CN # 语言中文设为 zh-CN timezone: Asia/Shanghai # 时区这些信息会显示在博客的页眉、页脚以及生成的 HTML 元数据中是博客的“名片”。4.2 网址配置为部署到 GitHub Pages 做准备URL部分至关重要它决定了生成页面中链接的根路径。url: https://你的GitHub用户名.github.io # 你的 GitHub Pages 地址 root: / # 如果部署到非根目录如 username.github.io/project则改为 /project/ permalink: :year/:month/:day/:title/ # 文章永久链接格式 permalink_defaults: pretty_urls: trailing_index: false # 移除链接末尾的 index.html对于最基本的个人主页型 GitHub Pages (username.github.io)url就按上面填写root保持为/。permalink定义了你的文章链接样式:year/:month/:day/:title/是一种常见且清晰的结构。4.3 部署配置一键上线的魔法这是连接本地和 GitHub 的关键。找到Deployment部分修改如下deploy: type: git # 部署类型 repo: github: gitgithub.com:你的GitHub用户名/你的GitHub用户名.github.io.git # 推荐SSH地址 # 或者使用HTTPS地址https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git branch: main # 部署到的分支GitHub默认主分支现在是 main message: Site updated: {{ now(YYYY-MM-DD HH:mm:ss) }} # 可选的提交信息这里解释一下repo的两种地址SSH地址(gitgithub.com:...): 如果你配置了 SSH 密钥就用这个以后部署不需要输密码。HTTPS地址(https://github.com/...): 如果没配 SSH 密钥就用这个每次部署需要输入 GitHub 账号密码或 Personal Access Token。实操心得强烈建议使用 SSH 方式一劳永逸。确保你的 SSH 密钥已添加到 GitHub并在命令行中用ssh -T gitgithub.com测试连接是否成功看到欢迎信息即成功。配置好后你需要安装 Hexo 的 Git 部署插件npm install hexo-deployer-git --save这个插件会读取上面的配置并帮你完成将public文件夹推送到 GitHub 仓库的复杂操作。4.4 其他实用配置new_post_name: :title.md 新建文章的文件名格式保持默认即可。default_layout: post 默认布局新建文章时使用。highlight: 代码高亮设置。建议启用并选择一个喜欢的主题例如highlight: enable: true line_number: true auto_detect: true tab_replace: wrap: true hljs: false这样你的代码块就会有行号和语法高亮了。修改完_config.yml后建议执行hexo clean hexo g重新生成然后用hexo s在本地查看配置是否生效。配置文件是静态博客的基石花点时间理解它后续的定制化会顺利很多。5. 主题选择与深度定制打造独一无二的视觉风格Hexo 默认的landscape主题功能简单颜值一般。社区有大量优秀的第三方主题比如 NexT、Butterfly、Matery 等它们提供了丰富的功能和现代化的设计。这里我以目前非常流行且功能强大的Butterfly主题为例讲解如何安装和配置。5.1 安装 Butterfly 主题在你的博客项目根目录下执行git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly这会将 Butterfly 主题的代码克隆到themes/butterfly目录下。5.2 启用主题打开根目录的_config.yml找到theme字段将其修改为theme: butterfly5.3 主题配置复制与覆盖Butterfly 主题有自己独立的配置文件themes/butterfly/_config.yml。但是最佳实践不是直接修改这个文件因为主题更新时你的修改会被覆盖。正确做法是在博客根目录下创建一个名为_config.butterfly.yml的文件如果使用 NexT 主题则是_config.next.yml然后将主题原配置文件中你需要修改的部分复制到这个新文件里进行修改。例如你想修改导航菜单和网站图标从themes/butterfly/_config.yml中找到menu和favicon相关配置。将其复制到根目录的_config.butterfly.yml中。在_config.butterfly.yml里进行修改# 导航菜单 menu: 首页: / || fas fa-home 归档: /archives/ || fas fa-archive 标签: /tags/ || fas fa-tags 分类: /categories/ || fas fa-folder-open 关于: /about/ || fas fa-user-circle # 你可以添加更多如友链 # 友链: /link/ || fas fa-link # 网站图标 favicon: /img/favicon.ico # 将你的 favicon.ico 图片放在 source/img/ 目录下Hexo 在生成时会优先使用根目录下这些_config.[theme].yml文件中的配置来覆盖主题默认配置。这样就实现了配置与主题代码的分离便于管理和升级。5.4 常见功能配置示例侧边栏头像与社交链接# _config.butterfly.yml avatar: img: /img/avatar.jpg # 头像路径 effect: true # 是否开启旋转效果 social: fa-github: https://github.com/你的用户名 || fab fa-github fa-envelope: mailto:你的邮箱 || fas fa-envelope # 更多图标参考 Font Awesome文章打赏reward: enable: true QR_code: - img: /img/wechatpay.png link: text: 微信 - img: /img/alipay.png link: text: 支付宝评论系统Butterfly 支持多种评论插件如 Valine、Waline、Gitalk 等。以 Waline 为例你需要先在 Vercel 等平台部署 Waline 服务端获取服务端地址。waline: serverURL: https://your-waline-domain.vercel.app # Waline 服务端地址 lang: zh-CN visitor: true # 文章阅读量统计 commentCount: true # 显示评论数搜索功能安装hexo-generator-search插件。npm install hexo-generator-search --save在根目录_config.yml中添加search: path: search.xml field: post format: html limit: 10000然后在_config.butterfly.yml中启用本地搜索。主题的配置项极其丰富包括动画效果、字体、代码高亮样式、页脚信息等等。建议你访问 Butterfly 主题的官方文档对照文档逐一探索和配置。这个过程就像装修自己的房子虽然繁琐但成就感十足。配置完成后执行hexo clean hexo g hexo s在本地仔细检查每一个页面的效果确保一切如你所愿。6. 写作与管理让创作流程化博客的核心是内容。Hexo 让写作和内容管理变得非常高效。6.1 创建一篇新文章使用一条简单的命令hexo new 我的第一篇文章Hexo 会在source/_posts目录下生成一个 Markdown 文件文件名通常是我的第一篇文章.md。文件开头是“Front-matter”这是用三条短横线包裹的 YAML 区域用于设置文章的元数据。6.2 理解 Front-matter打开新生成的文章你会看到类似这样的结构--- title: 我的第一篇文章 date: 2024-05-27 14:00:00 tags: - 教程 - Hexo categories: 建站 ---这是文章的“头信息”Hexo 根据它来处理文章。你可以添加更多字段title: 文章标题。date: 发布时间可手动修改。updated: 更新时间可选。tags: 标签支持多个用数组表示[标签1, 标签2]或列表形式。categories: 分类。可以是字符串建站也可以是层级分类[建站, 教程]。permalink: 覆盖全局的永久链接可选。cover: 文章封面图路径主题支持时。toc: 是否显示文章目录Table of Contents。mathjax: 是否启用数学公式渲染。6.3 编写文章内容在 Front-matter 下方就可以用 Markdown 语法畅快书写了。Hexo 支持所有标准 Markdown 语法并扩展了一些有用的标签插件例如引用站内文章{% post_link 文章文件名不含.md ‘文章标题’ %}插入图片{% asset_img 图片文件名.jpg 图片描述 %}图片需放在source/_posts同名的文章资源文件夹内通过hexo new时加--path参数创建代码块使用三个反引号包裹并指定语言。我的写作流程通常是用 VS Code 打开博客项目在_posts里新建文件用 Markdown 写作配合 Paste Image 等插件直接粘贴截图图片会自动保存到对应目录。写完一段就用hexo s实时预览非常方便。6.4 创建独立页面除了文章你还可以创建“关于”、“友链”、“标签云”等独立页面。创建页面hexo new page about这会在source目录下生成一个about文件夹里面包含index.md文件。编辑页面像写文章一样编辑这个index.md文件。它的 Front-matter 可以更简单通常只需要title和layout如果主题支持特殊的页面布局。在导航中显示记得去主题配置文件如_config.butterfly.yml的menu部分添加这个页面的链接如关于: /about/ || fas fa-user-circle。7. 部署到 GitHub Pages让全世界看到你的博客当你在本地把博客打磨得差不多了就可以部署到 GitHub Pages让它公之于众。7.1 创建 GitHub 仓库这个仓库的名字有严格规定如果你想使用https://你的用户名.github.io这样的顶级域名那么仓库名必须是你的用户名.github.io。如果你想使用https://你的用户名.github.io/仓库名这样的项目页面那么仓库名可以任意。对于个人博客我们通常选择第一种。登录 GitHub点击右上角“”选择“New repository”。在 Repository name 中填入你的用户名.github.io选择 Public公开然后创建仓库。7.2 配置 SSH 密钥并测试连接如果你在环境准备阶段没有配置 SSH 密钥请返回 2.2 节完成。配置后在命令行测试ssh -T gitgithub.com如果看到Hi 你的用户名! Youve successfully authenticated...的提示说明连接成功。7.3 一键部署这是最激动人心的时刻。确保你的_config.yml中部署配置已正确填写见 4.3 节并且已安装hexo-deployer-git插件。在博客项目根目录下执行部署命令hexo clean hexo deploy -g # 或者分步执行 hexo clean # 清理 hexo generate # 生成静态文件 hexo deploy # 部署hexo deploy -g是generate和deploy的合并操作。命令执行过程中会提示你输入 GitHub 的用户名和密码如果使用 HTTPS 方式。如果使用 SSH 且配置正确则会直接开始推送。推送完成后稍等1-2分钟访问https://你的用户名.github.io你的博客就应该在线了7.4 自动化部署的进阶思路每次写文章都要执行hexo clean hexo deploy -g有点麻烦。更优雅的方式是利用 GitHub Actions 实现自动化。其原理是你将博客的源码包括 Markdown 文章、主题、配置文件推送到一个仓库比如blog-source然后 GitHub Actions 会自动在云端执行生成和部署命令将生成的public文件夹内容推送到你的用户名.github.io这个仓库。这需要编写一个.github/workflows/deploy.yml工作流文件。虽然初次设置稍复杂但一劳永逸。网上有大量现成的 Hexo 部署 Action 模板搜索“Hexo GitHub Actions”即可找到。这能让你从任何设备只需推送 Markdown 文件就完成博客更新。8. 高级技巧与疑难排坑即使按照教程一步步来也可能会遇到一些奇怪的问题。这里分享几个我踩过的坑和对应的解决方案。8.1 图片加载失败问题这是最常见的问题之一。本地预览正常部署后图片不显示。原因1路径错误。Markdown 中引用图片的路径是相对于最终生成页面的。最稳妥的方式是使用 Hexo 的标签插件{% asset_img %}或{% img %}取决于主题并将图片放在文章对应的资源文件夹内。解决方案使用“文章资源文件夹”功能。在根目录_config.yml中设置post_asset_folder: true之后使用hexo new命令创建文章时会自动生成一个与文章同名的文件夹。你可以把文章用到的图片都放进去。在文章中引用图片时使用{% asset_img 图片文件名.jpg 图片描述 %}Hexo 在生成时会正确处理路径。原因2图床问题。如果你引用的是网络图片图床请确保链接是 HTTPS 且稳定。8.2 主题样式或功能不生效检查配置覆盖确认你是否在正确的配置文件_config.butterfly.yml中修改了设置并且修改的格式缩进、冒号后的空格符合 YAML 语法。清除缓存每次修改主题配置后务必执行hexo clean再重新生成。Hexo 有缓存机制清理能避免很多诡异问题。查看主题文档确认你使用的功能是否需要额外安装插件或进行特定配置。例如某些主题的搜索功能需要单独安装hexo-generator-searchdb插件。8.3 部署失败报错“Permission denied (publickey)”这通常是 SSH 密钥问题。检查密钥是否添加确保~/.ssh/id_rsa.pub的内容已完整添加到 GitHub 的 SSH Keys 设置中。测试连接再次运行ssh -T gitgithub.com看是否成功。检查仓库地址确认_config.yml中的repo地址是 SSH 格式 (gitgithub.com:...)并且用户名和仓库名正确。检查本地密钥加载在 Windows 上可以尝试启动ssh-agent并添加密钥ssh-add ~/.ssh/id_rsa。8.4 自定义域名与 HTTPS想让博客拥有像blog.yourname.com这样的专属域名购买一个域名在阿里云、GoDaddy等平台。在域名管理后台添加两条 CNAME 记录记录类型CNAME主机记录记录值你的用户名.github.io记录类型CNAME主机记录www记录值你的用户名.github.io在你的博客项目source目录下创建一个名为CNAME的文件无后缀里面只写一行你的域名例如blog.yourname.com。重新部署博客 (hexo clean hexo deploy -g)。等待 DNS 生效可能需要几分钟到几小时。生效后GitHub Pages 会自动为你的域名启用 HTTPS。8.5 备份你的博客源码你的_config.yml、主题配置文件、Markdown 源文件这些才是你最宝贵的资产。一定要做好备份本地备份定期将整个博客项目文件夹除了node_modules和public这类可生成的目录压缩存档。云端备份在 GitHub 上创建一个私有仓库例如my-hexo-blog-source将你的源码推送到这个仓库。这样既实现了版本控制也完成了异地备份。.gitignore文件需要忽略node_modules、public、.deploy_git等目录。搭建博客是一个持续学习和打磨的过程。从最初的功能实现到后来的样式调整、性能优化、SEO 设置每一步都能学到新东西。最重要的是开始写坚持写。这个完全由你掌控的数字角落会成为你技术成长最好的见证。如果在实践中遇到任何教程未覆盖的问题善用搜索引擎Hexo 和各大主题的官方文档、GitHub Issues 区通常都能找到答案。祝你搭建顺利写作愉快