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 是我们整个项目的核心。它的工作模式非常清晰输入你写在source/_posts/目录下的 Markdown 文件你的文章以及_config.yml这个站点配置文件。处理Hexo 读取这些 Markdown 和配置根据你选定的“主题”的模板进行渲染。输出在public文件夹里生成一整套完整的、静态的 HTML 网站文件。这个过程是“静态”的意味着服务器每次访问时不需要像 WordPress 那样动态查询数据库、组装页面因此速度极快安全性也极高因为没有动态脚本执行漏洞。你本地写好运行hexo generate命令生成网站再用hexo deploy部署读者看到的就是最终结果。3. 本地环境搭建与初始化实战理论清楚了我们开始动手。请严格按照步骤操作我会指出每个步骤的关键点。3.1 第一步安装 Git 并完成基础配置下载安装访问 Git 官网下载对应你操作系统Windows/macOS/Linux的安装程序。Windows 用户一路“Next”即可安装时注意勾选“Git Bash Here”选项这样以后在文件夹里右键就能直接打开 Git 命令行非常方便。基础配置必须做安装完成后在任意地方右键选择“Git Bash Here”打开命令行窗口执行以下命令设置你的全局身份。这个信息会记录在你的每一次提交中。git config --global user.name 你的用户名 git config --global user.email 你的邮箱例如git config --global user.name zhangsangit config --global user.email zhangsanexample.com。这个邮箱最好和你后续注册 GitHub 的邮箱一致。检查安装输入git --version如果显示版本号如git version 2.40.1说明安装成功。3.2 第二步安装 Node.js 和 npm下载安装访问 Node.js 官网下载LTS版本长期支持版目前通常是 Node.js 20.x。同样是一路下一步安装。安装程序会自动将 Node.js 和 npm 添加到系统路径。验证与版本管理提示安装完成后打开一个新的命令行窗口CMD 或 PowerShell或者新的 Git Bash输入node -v npm -v应该分别显示 Node.js 和 npm 的版本号。如果这里报错“不是内部或外部命令”说明环境变量未生效重启电脑通常可以解决。配置 npm 镜像源国内用户必做npm 默认源在国外下载包速度很慢。我们需要将其切换到国内镜像如淘宝源。npm config set registry https://registry.npmmirror.com/执行后可以通过npm config get registry命令检查是否设置成功。3.3 第三步安装 Hexo 并初始化博客项目全局安装 Hexo 命令行工具在命令行中执行以下命令。-g代表全局安装这样你可以在任何目录下使用hexo命令。npm install -g hexo-cli安装完成后输入hexo -v检查会打印出 Hexo 及相关依赖的版本信息。初始化博客文件夹找一个你喜欢的目录例如D:\Projects在命令行中进入该目录然后执行hexo init myblog这个命令会创建一个名为myblog的文件夹并自动在里面生成博客所需的全部基础文件。cd myblog进入这个文件夹这是你未来所有操作的“工作目录”。安装项目依赖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 CtrlC 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主题为例。安装主题在博客根目录下运行以下命令。这会将 Fluid 主题下载到themes/fluid文件夹。npm install --save hexo-theme-fluid指定主题打开根目录的_config.yml找到theme配置项将其修改为theme: fluid创建主题配置文件Fluid 主题有自己独立的配置文件。你需要将主题提供的示例配置文件复制到博客根目录下并重命名。首先在node_modules/hexo-theme-fluid目录中找到_config.yml文件。将其复制到你的博客根目录与 Hexo 自己的_config.yml同级。将复制过来的文件重命名为_config.fluid.yml。实操心得为什么这么做Hexo 支持“数据覆盖”。_config.fluid.yml中的配置会覆盖主题包内默认的_config.yml。这样做的好处是当你将来通过 npm 更新主题时你的个性化配置不会丢失因为你的配置在博客根目录下不会被覆盖。配置主题现在打开_config.fluid.yml你可以进行深度定制。例如导航栏在navbar部分添加你的菜单。首页横幅在banner部分设置头图。主题颜色在color部分调整配色方案。页脚信息在footer部分修改版权信息。 每次修改主题配置后需要重启本地服务器CtrlC停止再执行hexo s才能看到效果。4.3 写作与发布你的第一篇文章创建新文章在博客根目录下运行命令hexo new 我的第一篇文章这会在source/_posts目录下创建一个名为我的第一篇文章.md的文件。编辑文章用编辑器打开这个.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 语法愉快地书写正文了。预览保存文件后回到浏览器localhost:4000刷新页面你就能看到新文章出现在列表中了。Hexo 服务器支持热更新对于文章内容的修改通常刷新即可看到但如果是修改了配置或新建了文章可能需要重启服务器或重新生成。5. 部署到 GitHub Pages让全世界看到你的博客本地博客再好也只能自己看。部署到 GitHub Pages就能获得一个yourusername.github.io的免费域名全球可访问。5.1 第一步创建 GitHub 仓库并配置 SSH 密钥注册 GitHub如果你没有账号先去 GitHub 官网注册。创建仓库登录后点击右上角“”号选择“New repository”。仓库名必须严格遵守格式你的用户名.github.io。例如你的用户名是zhangsan那么仓库名就是zhangsan.github.io。将仓库设为 Public公开然后创建。生成 SSH 密钥关键步骤为了让本地 Git 能安全地推送代码到 GitHub需要配置 SSH 密钥。打开 Git Bash输入ssh-keygen -t rsa -C 你的邮箱连续按三次回车接受默认设置。这会在C:\Users\你的用户名\.sshWindows或~/.sshmacOS/Linux目录下生成两个文件id_rsa私钥保密和id_rsa.pub公钥。用记事本打开id_rsa.pub文件复制里面的全部内容。在 GitHub 添加公钥进入 GitHub 设置页面找到“SSH and GPG keys”选项点击“New SSH key”。Title 可以随意填如“My Laptop”Key 类型选择“Authentication Key”然后将刚才复制的公钥内容粘贴进去保存。5.2 第二步安装部署插件并配置 Hexo安装hexo-deployer-git在博客根目录下运行npm install hexo-deployer-git --save配置部署信息打开博客根目录的_config.yml滚动到最底部找到deploy部分修改为deploy: type: git repo: gitgithub.com:你的用户名/你的用户名.github.io.git # 替换为你的仓库SSH地址 branch: main # 或 master取决于你的仓库默认分支名 message: Site updated: {{ now(YYYY-MM-DD HH:mm:ss) }} # 可选的提交信息重要repo地址务必使用SSH 格式即以gitgithub.com:开头而不是 HTTPS 格式。这能避免每次部署都要输入密码。5.3 第三步执行部署命令在博客根目录下执行部署三部曲hexo clean hexo generate hexo deploy或者简写为hexo clean hexo g -d命令执行过程会提示你输入 SSH 密钥的密码如果你之前设置了的话默认回车即可。部署成功后等待大约1-2分钟访问https://你的用户名.github.io你的个人博客就正式上线了6. 深度优化、问题排查与进阶技巧博客上线只是开始要让其好用、好看还需要一些优化和问题处理。6.1 常见问题与解决方案速查表问题现象可能原因解决方案执行hexo命令提示“不是内部或外部命令”Node.js 或 Hexo 未正确安装或环境变量未生效。1. 检查 Node.js 安装node -v。2. 重新全局安装 Hexonpm install -g hexo-cli。3. 重启命令行或电脑。本地hexo s后浏览器访问localhost:4000空白或报错。端口被占用或生成过程有错误。1. 尝试hexo clean hexo g hexo s。2. 换端口启动hexo s -p 5000。3. 检查命令行是否有红色错误信息。部署时 (hexo d) 报错fatal: not a git repository当前目录不是 Git 仓库或未初始化。在博客根目录执行git init初始化本地仓库。部署时提示Permission denied (publickey).SSH 密钥未配置或配置错误。1. 确认是否生成了 SSH 密钥对。2. 确认公钥id_rsa.pub内容是否正确添加到 GitHub。3. 测试连接ssh -T gitgithub.com应看到欢迎信息。访问 GitHub Pages 域名显示 404。仓库名错误、分支错误或首次部署需要时间。1. 确认仓库名为用户名.github.io。2. 确认_config.yml中deploy.branch与仓库默认分支一致现多为main。3. 在仓库的 Settings - Pages 里确认 Source 分支正确。4. 首次部署请等待几分钟再刷新。修改主题配置后本地预览无变化。浏览器缓存或 Hexo 未重新生成。1. 浏览器强制刷新CtrlF5。2. 执行hexo clean hexo g hexo s重启服务。3. 确认修改的是正确的配置文件根目录的_config.fluid.yml而非主题包内的。6.2 进阶优化技巧自定义域名如果你有自己的域名如blog.yourname.com可以在 GitHub Pages 仓库的 Settings 里设置 Custom domain并在域名服务商那里添加 CNAME 解析记录指向你的用户名.github.io。别忘了在博客根目录source文件夹下创建一个名为CNAME的文件无后缀里面只写一行你的域名。开启 HTTPSGitHub Pages 默认支持并强制 HTTPS确保你的博客连接是安全的。添加搜索引擎收录为了让百度、谷歌等搜索引擎收录你的博客需要生成站点地图。安装插件npm install hexo-generator-sitemap --save npm install hexo-generator-baidu-sitemap --save # 针对百度安装后重新生成部署访问你的域名/sitemap.xml和你的域名/baidusitemap.xml就能看到地图文件。然后将这些地址提交到各搜索引擎的站长平台。备份与多端同步你的整个博客文件夹除了node_modules和public因为它们可以通过npm install和hexo g重新生成就是一个完整的项目。你可以把整个文件夹用 Git 推送到另一个私有仓库比如叫myblog-source进行备份。换电脑时克隆这个源码仓库运行npm install安装依赖就能立刻恢复写作环境。写作流程自动化你可以编写简单的脚本将hexo clean hexo g hexo d这几条命令整合成一个比如在根目录创建deploy.sh文件每次只需运行这个脚本即可完成部署。6.3 主题选择与个性化建议除了 Fluid还有很多优秀的主题选择时可以考虑Butterfly功能极其丰富UI 美观可定制性极高社区活跃。NexT经典主题用户基数大文档和插件生态非常成熟。Stun设计感强动画效果出色。Icarus界面简洁专注于内容展示。更换主题的步骤大同小异通过 npm 安装或 Git clone 到 themes 目录然后在站点配置中修改theme名称即可。深度定制前务必先阅读该主题的官方文档。搭建个人博客的过程就像精心打理一个花园。从最初的荒地空白文件夹到打下地基环境搭建搭建框架初始化配置装修布置安装主题再到最终对外开放部署上线每一步都充满创造的乐趣。这个博客将完全属于你它不仅是内容的容器更是你学习能力、审美品味和技术实践的展示窗。遇到问题别怕搜索引擎、Hexo官方文档和社区是你最好的老师。现在开始写下你的第一篇博客吧。