Hexo这个静态博客框架我从第一次接触到现在用了快五年中间折腾过好几个主题、换过部署方式也帮不少朋友排查过搭建过程中遇到的坑。这篇文章不是简单的命令罗列而是把我实际踩过的坑和沉淀下来的经验整理出来尤其是在部署GitHub Pages和排查“public下没有生成index.html”这类问题上给你一套可以直接照做的解决方案。无论你是完全没接触过命令行的小白还是已经试过Hexo但卡在某一步的老手这篇文章都能帮你减少试错的时间。我会从环境准备讲起一步步带你走到线上访问再单独拿出一大节来剖析那个让人头疼的“index.html没生成”问题。1. 梳理需求为什么选Hexo而不是WordPress或纯手写1.1 Hexo到底是什么和动态博客有什么本质区别Hexo是一个基于Node.js的静态博客生成器。说人话就是你在本地用Markdown写文章然后Hexo这套程序会把这些Markdown文件套上模板、处理成纯静态的HTML页面最后生成一个完整的网站文件夹。你要做的只是把这个文件夹里的内容扔到服务器或者GitHub Pages上就能让别人通过网址访问。这和WordPress那种动态博客有本质区别。WordPress有后台管理界面、有数据库每篇文章都是动态从数据库里查出来的服务器需要PHP环境和MySQL服务。而Hexo生成的网站本质是一堆提前做好的HTML文件不依赖数据库服务器只需要把文件原样吐出来就行。用生活里的事情打比方WordPress像是一家有厨房的餐厅客人点菜后现炒Hexo则像一家预制菜门店菜品已经做好了客人来了直接拿走。正因为这个特性Hexo部署的网站几乎不会出现数据库挂了、后台被攻击这类问题访问速度也快得感人。你在GitHub Pages这种免费托管平台上随便一个页面都是毫秒级加载因为本质上浏览器拿到的就是一个个静态文件没有任何后端计算过程。1.2 什么样的场景适合用Hexo什么样的不适合我用下来的体会是Hexo最适合这几类人写技术博客、学习笔记、个人日记这类以文字内容为主的站点希望把精力放在写内容上而不是花大量时间维护服务器、更新系统、修漏洞熟悉或者愿意学一点Markdown语法和基础的Git命令想要零成本或者极低成本上线博客特别是挂在GitHub Pages或Gitee Pages上。反过来如果你打算做电商网站、需要复杂的会员系统、要接入在线支付或者你的读者群体需要在网页上注册登录那Hexo并不合适。虽然也有评论区插件但都是第三方方案数据不在你手里交互体验和真正动态网站还是有差距。我见过不少人拿着Hexo硬做企业官网最后在表单提交、用户管理这些功能上卡得要死然后反过来骂Hexo难用。本质上是选错了工具。我的建议其实很简单先想清楚你的博客未来一年内的定位。如果定位就是写文章Hexo的性价比非常高如果你已经预感到要做很多动态交互功能那早一点上WordPress或Halo这类动态方案可能更稳妥。2. 环境准备Node.js、Git与Hexo安装2.1 Node.js安装与版本选择Hexo是基于Node.js运行的程序所以第一步就是把Node.js装好。很多人会忽略版本问题直接装最新版结果后面跑npm install的时候各种依赖报错其实多数时候不是Hexo本身的问题而是Node.js版本和Hexo的依赖不兼容。我个人建议装LTS版本也就是长期支持版。去Node.js官网下载时会看到两个按钮一个写着LTS一个写着Current请选LTS。如果你用的操作系统是Windows直接下载那个.msi安装包一路下一步就可以。macOS用户建议用Homebrew安装命令是brew install nodeLinux用户则根据发行版用apt或者yum装。这里有个小技巧装完Node.js之后在终端运行node -v和npm -v这两条命令能看到版本号说明安装成功。如果提示“不是内部或外部命令”之类的话多半是环境变量没配好。Windows用户可以在“系统属性-环境变量”里检查一下Node.js的安装路径有没有加到PATH里正常安装的话这个步骤是自动完成的。2.2 Git安装与常用配置Git是另一个必备工具。因为后面把博客部署到GitHub Pages时本质上是把本地的静态文件推送到GitHub仓库里这个推送动作靠的就是Git。就算你不打算用GitHub我仍然建议装上Git因为Hexo初始化博客时部分流程也需要借用Git的能力。Windows直接下载Git官网的安装包一路下一步就行。macOS可以用brew install git也可以直接安装Xcode Command Line Tools时自带的Git。安装完毕后在终端跑git --version确认装好了。打开终端先做两件基础配置让Git知道你是谁git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条配置会写进你每次提交记录的作者信息里。很多时候你部署后发现GitHub上的提交记录显示成别人的名字或者提交被拒绝就是因为这里没配置好。我身边一个朋友就是这样用户名没设置GitHub认不出他是仓库管理员推送代码被拒了整整一下午最后才发现是这个原因。2.3 安装Hexo CLI并验证版本环境装好之后安装Hexo的命令行工具npm install -g hexo-cli-g参数表示全局安装这样你可以在任意目录下直接敲hexo命令。安装过程中如果看到一堆warning一般不用管只要不是error结尾就问题不大。装完之后验证一下hexo version如果能看到一行一行的版本信息说明Hexo已经装好了。这里我特别提醒一句建议你在某个固定目录下建博客项目比如~/blog或者D:\blog不要装在C盘系统盘后混在一堆乱七八糟文件里。因为Hexo项目会生成大量小文件放在干净目录里无论是备份还是迁移都方便得多。3. 初始化博客与发布第一篇文章3.1 hexo init带你生成的目录结构到底怎么看选一个干净目录执行hexo init my-blog这个命令会下载Hexo默认的博客模板。下载过程中可能有点慢因为要从npm拉取依赖包如果你的网络状况不太好可以考虑等一会儿或者在npm配置中切换国内镜像源。下载完成后进入目录cd my-blog npm installnpm install会把博客项目依赖的各类npm包装到本地的node_modules文件夹里。装完后用编辑器打开这个目录你会看到以下这些关键文件和文件夹_config.yml博客的全局配置标题、描述、URL、部署信息都在这里。scaffolds新文章的模板文件夹里面有post、page、draft三个模板文件。source你的文章存放处写好的Markdown文件都放这里。themes主题文件夹你下载的每个主题都有独立目录。package.json依赖和脚本配置。public运行生成命令后自动产出的文件夹也就是最终要部署的网站文件。很多新手容易犯一个错误搞不清楚source和public的区别。source是你写文章的地方是源文件public是Hexo根据源文件和主题生成的成品网站。你改文章改的是source里的文件改完必须重新执行生成命令public里的内容才会更新。大多数人问的“public下没有生成index.html”就和这个流程有关我后面会专门拿一节来展开讲。3.2 全局配置_config.yml的必改项用编辑器打开根目录的_config.yml这个文件是Hexo的“总开关”里面的每一项都值得仔细看一遍。我挑几个必须改的项目说一下title: 你的博客名称 subtitle: 副标题 author: 你的昵称 language: zh-CN url: https://你的用户名.github.iourl这一项最容易被忽略却影响很多功能。它代表了你的博客最终访问地址如果你没有填后面生成站点地图、做SEO优化、分享文章链接时都会出问题。很多人第一次部署完发现文章页面的链接不对就是因为url没有配置成实际的线上域名。还有一种情况是你前期在本地预览还没买域名也没决定用哪个托管平台。我的建议是先用你计划部署的平台域名填进去比如GitHub Pages就是https://用户名.github.io后续如果换了域名再回来改这个配置同时还要把source目录下所有文章里的绝对链接处理好。3.3 创建第一篇文章和Front Matter写法万事俱备现在创建第一篇文章hexo new 你好Hexo这条命令会在source/_posts目录下生成一个名为你好-Hexo.md的文件。用编辑器打开你会看到头几行是类似这样的一段--- title: 你好Hexo date: 2024-01-15 10:30:00 tags: ---这段以---包裹的内容就叫Front Matter是Hexo读取文章元数据的关键。你可以在这里设置title标题、date日期、tags标签、categories分类等字段。比如我想写一篇分类在“教程”下、打上“Hexo”和“部署”标签的文章就可以这样写--- title: 使用Hexo搭建个人博客教程 date: 2024-01-15 10:30:00 categories: - 教程 tags: - Hexo - 部署 ---之后在---下方直接用Markdown语法写正文就行。段落、标题、代码块、图片引用都按Markdown的规则来。我自己习惯在文章开头加一段摘要用!-- more --来做“”的分隔符这样首页列表不会把整篇文章都摊开看起来清爽很多。3.4 本地预览到底卡在哪一步文章写好后想预览效果在项目根目录执行hexo server终端会提示类似INFO Hexo is running at http://localhost:4000的信息。在浏览器打开这个地址你就能看到本地版本的博客。如果4000端口被其他程序占用了启动时会报错。这时候指定一个空闲端口就行hexo server -p 5000本地预览阶段还有几个高频坑改完_config.yml或者主题配置后很多人发现刷新页面没反应。这很正常hexo server虽然带了一个简单的监听机制但某些配置修改它不一定能感知到。我的建议是按下CtrlC停掉服务重新执行hexo server确保配置生效。4. 部署到GitHub Pages从仓库创建到域名访问4.1 创建GitHub仓库名字千万别写错部署到GitHub Pages的第一件事是去GitHub上创建一个仓库。这里有个关键规则仓库名必须写成你的用户名.github.io。比如你的GitHub用户名是zhangsan仓库名就必须是zhangsan.github.io因为这个特殊名字对应了GitHub Pages默认分配的域名地址。如果你没按这个规则来部署成功后网址和仓库名对不上访问就会出现404。这个错误太常见了。我当时第一次部署时把仓库名起成了my-blog折腾半天怎么都访问不了后来才意识到问题出在仓库名上。创建仓库时面板上还能选Public或Private。如果你想让博客被公开访问必须选Public因为GitHub Pages服务不会为Private仓库提供公开站点。4.2 SSH密钥配置让本地Git和GitHub互相认识在本地终端运行ssh-keygen -t rsa -b 4096 -C 你的邮箱运行后可以一路回车默认选项即可。之后你会得到两个文件id_rsa私钥和id_rsa.pub公钥。私钥留在本地公钥要配置到GitHub账户里。查看公钥内容的命令cat ~/.ssh/id_rsa.pub复制显示的整段内容然后打开GitHub网站进入Settings-SSH and GPG keys-New SSH key把公钥粘贴进去保存。这样操作之后本地Git推送到GitHub仓库时就不需要反复输入账密了。验证SSH是否配置成功ssh -T gitgithub.com如果看到类似Hi zhangsan! Youve successfully authenticated的提示说明配置成功。这一步卡住的人很多常见问题是公钥粘贴时多了换行符或者空格导致GitHub识别不了。建议粘贴前确认公钥完整结尾没有多余内容。4.3 安装部署插件并修改deploy配置Hexo默认自带的部署能力只能生成静态文件要把文件推送到GitHub仓库还需要安装一个专门的插件npm install hexo-deployer-git --save装完插件后打开根目录的_config.yml在文件末尾找到或者添加deploy字段deploy: type: git repo: gitgithub.com:你的用户名/你的用户名.github.io.git branch: main注意repo这里填的是SSH协议的地址不是HTTPS的地址。你可以去GitHub仓库页面找到“Code”按钮切换到SSH标签页后就是这种gitgithub.com:...格式的地址。用SSH地址的好处是推送时不用每次输入用户名密码配合前面配置的SSH密钥整个部署过程可以做到完全无缝。4.4 完整部署三步曲clean、generate、deploy部署前我习惯先执行三连命令hexo clean hexo generate hexo deployhexo clean负责清掉public文件夹里的旧文件避免残留垃圾文件导致线上出现奇怪问题。hexo generate会根据你的源文件和主题重新生成public文件夹。hexo deploy把public文件夹里的内容推送到GitHub仓库。部署完成后在浏览器访问https://你的用户名.github.io正常情况下就能看到你的博客了。如果第一次访问出现404别慌。GitHub Pages部署有一定延迟尤其是首次设置后可能需要几分钟。有时候你去仓库的Settings-Pages页面能看到部署状态确认那里显示已发布后再刷新浏览器。4.5 部署后常见问题没生效、样式丢失、404部署成功后我发现很多人还会遇到三个常见问题。第一个是页面能打开但样式完全丢失整个页面看起来像没有穿衣服一样。这个大概率是_config.yml里的url没有配置导致CSS和JS资源的引用路径变成了相对路径浏览器找不到资源文件。把url改成正确的线上地址重新clean、generate、deploy一次样式就能恢复。第二个问题是文章能访问但首页打不开或者首页白屏。有时候是主题和Hexo版本不兼容导致的换一个维护活跃的主题就能解决。第三个问题是访问时给浏览器缓存了旧版本。因为Hexo生成的静态文件每次部署内容可能改变但文件名没变一些浏览器会缓存旧内容。我通常会在_config.yml里配置一个固定的资源版本号或者部署时手动给public文件夹加一层带时间戳的目录。不过对个人博客来说换个无痕窗口看效果最省事。5. 排查实录hexo public下没有生成index.html5.1 这个问题的典型症状到底是什么很多人在本地预览没问题可一旦执行hexo generate想看看public文件夹里生成了什么结果打开发现文件夹里空空如也或者只有几个子目录却找不到那个关键入口文件index.html。还有一种情况是部署到GitHub后访问域名出现404或者直接列出目录结构一眼就知道根本没有部署成功。这个问题之所以让人抓狂是因为Hexo本身并不报错。终端可能显示INFO Generated in 3.2s看起来一切正常但实际结果却是空的。我第一次遇到时也很懵后来排查多了才摸清楚原因。5.2 原因一执行了hexo clean后忘了hexo generate这是最傻也最常见的情况。很多人的习惯是先执行hexo clean觉得这个命令会把旧的生成文件清干净然后就直接执行hexo deploy。但没有public文件夹内容的时候hexo deploy根本无东西可推线上自然也是空的。这个操作顺序问题我建议记成固定套路clean和generate必须成对出现deploy只是把generate的结果送出去。如果你发现public是空的第一步就是看看自己刚才有没有执行过generate。可以先执行hexo generate然后重新看public文件夹如果index.html出现了那问题就已经解决后面部署就不会再有这个报错。5.3 原因二source/_posts目录下的文章为空或Front Matter格式错误有时候hexo generate执行了但public文件夹依然没有index.html。这时候就要检查你的文章源文件了。Hexo生成首页列表时要读取source/_posts目录下的所有文章信息。如果某篇文章的Front Matter格式写错了比如漏了冒号、缩进混乱或者日期格式不对Hexo在解析时可能就会跳过它甚至整个生成过程静默失败。我遇到过一个很典型的案例有篇文章的date字段写成了2024-01-15 10:30少了秒的部分Hexo解析时报错但不中断最后生成出来的首页就是空的。你检查自己的Markdown文档时特别要注意Front Matter里每个字段的冒号后面必须有一个空格date和tags的格式严格按照官方示例写。5.4 原因三主题配置乱了或主题本身有问题如果你确认文章没问题public依然没有index.html那问题很可能出在主题上。Hexo默认会带一个叫landscape的简洁主题。如果你在_config.yml里改成了某个第三方主题但这个主题的目录结构不完整缺少layout文件夹或者里面的模板文件有语法错误这会导致Hexo在渲染时出现问题。最狠的是有些主题的README里写得不明不白你下载下来后发现它的文件布局根本不是Hexo标准结构生成时自然得不到想要的输出。排查方法是先把_config.yml里的theme字段改回默认的landscape重新执行hexo clean hexo generate看看public文件夹里有没有index.html。如果有了说明第三方主题的兼容性有问题你需要换一个主题或者手动修复主题目录结构。5.5 原因四node_modules依赖缺失或损坏还有一类比较隐蔽的问题出在依赖上。你从网上拷贝了一个现成的Hexo项目或者自己初始化了博客之后执行了npm install但由于网络原因装到一半中断某些依赖缺失或损坏也会导致生成结果异常。这时候最有效的办法是删掉node_modules文件夹重新安装依赖rm -rf node_modules npm installWindows系统上删除node_modules麻烦一点可以用管理员权限打开命令行或者直接用文件管理器删除。重新安装依赖后再执行hexo clean hexo generate大概率能解决。5.6 最后的排查顺序我整理成了固定套路每次遇到“public下没有index.html”的问题我都会按下面这个顺序排查基本上能解决九成情况执行hexo clean和hexo generate确认问题依然存在。打开source/_posts检查所有文章Front Matter格式是否正确空文件直接删掉。把_config.yml中的theme改回landscape重新生成做对照。删除node_modules重装依赖。如果以上都不行看终端有没有error级别的日志把日志内容贴出来搜索多数情况下能找到同类问题的解法。还有一种比较罕见的情况就是你给_config.yml里配置了自定义的public_dir字段把输出目录改到了别的位置。检查一下这个字段确保它指向的是你自己以为的那个文件夹。6. 常见问题速查与后续优化6.1 高频问题速查表我把这几年被问到最多的问题整理成一张表方便你随时回来查阅问题现象大概率原因解决动作本地预览无法访问端口被占用hexo server -p 5000换个端口部署到GitHub后404仓库名不是用户名.github.io重建仓库或改仓库名部署后样式丢失_config.yml里url没设置配置正确的线上URL后重新部署页面能打开但图片不显示图片路径是绝对路径或文件名含中文使用相对路径或调整URL编码hexo deploy提示找不到命令没安装hexo-deployer-git执行npm install hexo-deployer-git --save写了新文章但线上没有更新忘了执行generate和deploy执行hexo clean hexo generate hexo deploy生成时提示数据库锁错误上次程序异常退出删掉db.json后重新生成修改主题不生效主题缓存没刷新执行hexo clean后重新生成6.2 主题替换的方法与仓库备份建议换主题是折腾博客的一大乐趣。我从默认的landscape换到NexT后来又换过几次操作流程基本一致去GitHub上把目标主题的仓库克隆到themes目录下然后在_config.yml里把theme字段改成主题文件夹的名字重新生成预览。但这里有个坑主题文件夹里一般也有一个自己的配置文件有的叫_config.yml有的叫_config.toml。它的配置项和博客根目录的_config.yml是两回事很多新手混淆了以为改根目录的配置就能控制主题的样式结果调了半天没反应。主题内部的标题、菜单、颜色、社交链接都应该去主题自己的配置文件里改。关于备份我强烈建议你用Git管理整个博客项目。不仅source里的文章要纳入版本控制连_config.yml和scaffolds模板都应该纳入。每次写完文章、改完配置就提交一次这样即使以后电脑出了故障也能随时从仓库恢复。我自己就是靠这套方式在换了两台电脑的情况下博客内容一份没丢。6.3 几个让博客更好用的提升方向基础搭建完成之后下面这几个方向你可以根据自己的需要选择性扩展第一是评论系统。Hexo没有自带评论区可以选择接入第三方评论服务让读者能在文章底部交流。如果不想用第三方服务也可以自己搭建一个后端支撑但维护成本稍高。第二是站内搜索。默认的Hexo没有站内搜索功能本地预览时用浏览器搜索的话只能找当前页面没法跨文章搜。可以通过安装搜索插件或接入第三方搜索服务给博客加上全文搜索能力。第三是SEO优化。安装sitemap生成插件生成站点地图后提交到搜索引擎让百度、必应能更快收录你的文章。同时注意每篇文章的标题、摘要和关键词的配置。第四是CDN加速。如果你用的是GitHub Pages国内访问速度有时不太稳定。可以绑定自己的域名再套一层CDN服务来加速静态资源。这一步不是必须的但如果你有访客主要在国内建议尽早规划。还有一个非常实用的小技巧每次部署前写一个简单的脚本把clean、generate、deploy三步连起来跑。我自己在项目根目录放了一个deploy.sh脚本内容就三行命令以后部署只需要执行一次。Windows用户可以考虑创建一个.bat文件或者在终端里也执行一样的命令序列逻辑是相同的。回顾搭建过程中那些最容易被低估的环节我个人在多次搭建Hexo博客的过程中最大的体会是这个框架本身不难难的是你愿不愿意静下心把每一步的原理搞清楚。很多人安装时一步到位然后急于求成结果在部署环节被一个index.html的问题卡住一卡就是半天。实际上这些问题都有规律按照靠谱的排查顺序多半能在几分钟内定位。回过头来想Hexo最打动我的地方在于它把写博客这件事变得非常纯粹。你只需要关注内容本身其他技术细节都能通过配置和插件解决。这种低负担的写作体验恰恰是和各类重型建站方案最大的不同。希望这篇教程能帮你顺利越过那些坑让你的博客从今天起真正跑起来。