从空仓库到第一篇博客Windows下用HEXO把博客页面真正跑起来上篇我们把GitHub Pages的仓库建好、权限理顺了但说句实话那种手动写HTML再推上去的方式撑死写两篇三篇就烦了——每篇都要套一遍完整的头部、导航、侧栏改个样式还得全局翻。所以这次直接上HEXO把本地写文章、生成静态页面、一键部署这条链路彻底打通。这篇只讲Windows环境下的实操从装环境到第一篇正式文章落地再到现在你敲完命令就能打开博客看到的完整路径。适合的读者是已经注册好GitHub账号、建好了以用户名命名的Pages仓库但卡在“不知道本地怎么搞”这一步的人。同时也劝退一种人——如果你只想原地写几篇Markdown、连版本管理都懒得碰那HEXO可能是负担留在手动HTML就行。但如果你想认真运营一个技术博客把写作、发布、回滚、主题定制都掌握在自己手里HEXO这套组合拳确实值得吃透。1. 为什么是HEXO而不是别的静态博客选型的逻辑先理清楚没接触过静态博客生成器的人第一次听HEXO可能会懵我文章明明写在本地怎么就能变成一个网站了这里面其实就两条线——本地有一条“内容生产流水线”远端有一个“静态页面托管仓库”两者之间靠生成和部署命令对接。1.1 生成器到底干了什么Markdown进去整套站点出来你写博客时主要面对的是Markdown文件它只负责记录文字、标题、列表、代码块不含任何页面骨架。HEXO这类静态生成器做的事情就是把这些Markdown文件套进预先定义好的主题模板里渲染成一整套HTML、CSS、JavaScript文件——也就是真正浏览器能看懂、能渲染的静态站点。整个过程可以类比成“印刷”Markdown是原稿主题模板是排版版式生成命令按下之后所有文章被统一排版成批量印刷品。传统动态博客比如WordPress是“读者每一次访问服务端都现场组装一次页面”而HEXO是“组装动作提前在本地完成服务端只负责把现成的文件原样端出去”。这两者最直观的差异就是速度纯静态文件部署出去几乎不用等服务器运算打开速度天然就快。而且静态站点还有个隐性好处——不容易被入侵。没有动态脚本在服务器上运行攻击面小了一大圈。对个人博客来说安全性、速度、可维护性这三样静态生成方案基本都占齐了。1.2 HEXO在同类工具里的位置Node.js生态是它最大的底气静态博客生成器其实有不少选择比如JekyllRuby生态、HugoGo生态、VuePressVue生态等。HEXO能成为很多人的入门首选主要靠两点一是Node.js生态普及度高前端开发者几乎都有现成环境装起来没有额外心智负担二是主题和插件数量可观几百个主题里总能挑到顺眼的想要评论、搜索、站点统计都有对应插件。还有个很实际的原因是文档和中文社区资源丰富。对国内开发者来说遇到问题搜一下能搜到大量现成的踩坑记录这种“社区成熟度”在我眼里比某些工具本身的功能亮点还值钱。你在Windows下遇到个编码问题很可能在你之前已经有几十个人问过、答过复制答案就能解决。1.3 Windows用户需要提前建立的三个心态第一命令行不是洪水猛兽。HEXO的核心操作就那几条命令hexo init初始化、hexo new写新文章、hexo g生成页面、hexo s本地预览、hexo d部署上线。把它们当成“跟电脑对话的固定短语”就行不需要懂底层原理也能玩得转。第二Node.js环境是必须跨过去的门槛。后面会详细讲这里先打个底HEXO基于Node.js运行没有它一切无从谈起。有不少人卡在安装环节就放弃实在可惜——装环境其实跟在Windows上装任何软件没有本质区别只是多了一个“环境变量”概念需要理解。第三版本兼容性要放在心上。Node.js版本太新或太旧都可能导致HEXO安装报错这跟“越新越好”的直觉相反。我用的是Node.js的LTS版本长期支持版配合HEXO 6.x和7.x都跑过整体很稳定。建议你装LTS别追新追新是给自己找坑。2. 开工前的准备Node.js与Git的环境坑位没环境就跑不了HEXO但装环境本身也有讲究。很多人栽在“明明装好了命令却提示找不到”这一节把这些坑提前填平。2.1 Node.js安装的版本选择与验证方式去官网下载LTS版本安装包。选版本的时候注意查看HEXO官方文档中对Node.js版本范围的要求不同版本的HEXO对Node版本的要求有差异。保守做法是选当前时间的LTS版本比如我这边用Node.js 18.x或20.x都没有问题。安装过程基本是“下一步下一步”但有两个细节容易被忽略安装路径不要带空格和中文。某些工具对路径解析有兼容问题干脆从一开始就把路径设置成全英文简单目录比如D:\Nodejs。装完之后要验证是否真正生效。打开一个新的PowerShell窗口不是安装前打开的那个旧窗口执行node -v npm -v如果两个命令都能输出版本号说明Node.js和随附的npm都装好了。如果提示“无法识别”大概率是环境变量没刷新——重开终端基本就能解决。2.2 Git安装与“命令存在于安装目录但终端不认”的经典问题HEXO部署到GitHub Pages需要调用Git完成推送所以Git也是必装项。同样注意路径全英文、安装选项里建议开启“从命令行使用Git”的选项这样PowerShell里才能直接用git命令。我见过很多开发者在终端里执行git却提示找不到命令但Git明明装好了。原因多半是安装时没有勾选把Git加入PATH的选项或者安装后没有重新打开终端。遇到这种情况重新运行Git安装包在调整PATH的步骤里选择“推荐设置”然后重新打开终端验证git --version2.3 提前配好Git身份信息部署时少踩身份认证的坑初始化和后续部署都用得着Git的用户信息建议安装完Git就先配好git config --global user.name 你的用户名 git config --global user.email 你的邮箱注意这里的用户名和邮箱不一定非要用GitHub上那个但建议保持一致这样提交记录里显示的作者信息是认得的后面排查问题也少一层迷惑。尤其邮箱GitHub要求邮箱验证过才能正确关联提交记录。这个环节看起来跟HEXO没什么直接关系实际上等部署阶段真出了身份认证问题再回头配就很绕。提前配好的意义是在“部署那一步”之前把变量清零。3. 从初始化站点到第一篇文档落地的完整路径环境备齐后核心流程正式启动。这一节从建站命令开始把每一步该干什么、命令会产生什么效果讲清楚。3.1 hexo init初始化一个博客骨架先在本地创建一个专门放博客的目录比如D:\myblog进入该目录后执行npm install hexo-cli -g hexo init .这句命令的逻辑是先全局安装HEXO的命令行工具然后在当前目录初始化博客骨架。init会自动拉取HEXO的基础模板包括配置文件_config.yml、主题目录themes、文章目录source/_posts以及默认的hello world文章。初始化完成后结构会是这样的_config.yml站点主配置文件。站点名称、作者信息、语言、部署配置等都写在这里。source/_posts/存放Markdown文章。themes/主题文件夹。node_modules/项目依赖模块。package.json项目依赖清单。初始化完成后建议立刻补装依赖npm install如果不执行这一步后面生成页面时大概率报缺模块的错误。3.2 本地预览把“看不见的站点”先跑起来靠hexo generate简写hexo g生成的静态文件其实可以直接扔到任意静态服务器上跑。但本地开发阶段我们更常用的是内置的开发服务器hexo server执行后终端会输出类似http://localhost:4000的地址在浏览器里打开就能看到你的博客框架和默认的hello world页面。这个本地预览服务很实用的一点是支持热更新——你改完Markdown文件刷新一下浏览器就能看到变化不用重新手动生成。3.3 真正写一篇文章hexo new的产物是什么默认的hello world只是试手用的真正的写作得靠新建文章hexo new 我的第一篇文章执行后会生成source/_posts/我的第一篇文章.md用任意文本编辑器打开会看到头部有一段YAML格式的front-matter--- title: 我的第一篇文章 date: 2024-01-01 12:00:00 tags: ---这里有一点经验之谈front-matter里的title字段可以留空直接设置为文件名对应的标题。但更推荐在文件里维护一个清晰的中文标题因为URL默认使用文件路径和文件名如果文件名叫中文或者很随意网址会很长很难看。我的习惯是文件名用英文或日期加英文而在front-matter中给出中文标题这样搜索引擎和阅读体验都更好。比如hexo new post/2024-01-01-welcome这样生成的路径会更干净而页面显示标题远处由front-matter里的title决定。3.4 Markdown写作的基本细节从“能写”到“想好好写”HEXO的正文内容就是标准Markdown#表示一级标题、##表示二级标题 包裹代码块插入图片。这些基础语法不展开讲了这里想强调两个HEXO场景下的特殊细节第一如果文章里嵌代码块一定要指定代码语言。比如写JavaScript片段就写javascript console.log(hello world); 代码高亮基于语言标识符。不写的后果是代码块缺少语法高亮阅读体验差一大截。代码块里的三个反引号也要留意如果代码内容本身含有三反引号需要在语法中处理否则会出现解析错乱。第二图片资源管理。HEXO默认情况下文章里的图片需要手工放到source/images目录并在Markdown里引用网络路径。本地路径直接写相对路径比较容易被生成器处理出错我的习惯是用一个图床服务或者把图片放到项目目录里后再用相对路径另外一个更省心的方法是把_config.yml里的post_asset_folder设置为true这样hexo new会为每篇文章单独建一个同名文件夹图片放进去之后用相对路径引用即可。hexo new 带图片的测试文章开启post_asset_folder后执行以上命令会在_posts下生成一个同名目录把图片丢进去然后用引用生成的页面图片路径不会错。4. 主题、配置与内容展示让页面别太素也别乱改HEXO默认主题非常朴素很多人第一眼看到会觉得“这也能叫博客”别急换主题和参数配置都在这一步完成。4.1 换主题的正确姿势Git clone的目录归属别放错到HEXO的官方主题库挑一个顺眼的主题假设叫某主题名称安装方式通常是git clone https://git.example.com/themes/某主题.git themes/某主题关键点是克隆到themes目录下而不是随便放到桌面或下载文件夹。主题目录的释放位置错了会导致HEXO完全找不到它。装好后修改主配置theme: 某主题然后重新hexo g生成、hexo s预览看效果。换主题这事我想多说两句很多人一上来就追求功能花哨的主题折腾两星期主题配置文章一篇没写。这是本末倒置的。主题能用、顺眼、不花哨就暂时够了写作内容才是博客的核心资产。我自己的博客换过三回主题每次换主题都要重新调整样式和插件时间成本极高。建议新人在最初的三五个月里锁死一个主流主题不动专心写内容。4.2 配置文件里的高频字段改之前先备份HEXO的主配置_config.yml里几个高频字段title: 博客标题 author: 作者名 language: zh-CN url: https://你的用户名.github.io其中url字段要特别注意。如果这里不填或填错后面部署后浏览器地址栏的链接可能指向旧域名导致页面能打开但CSS和图片全部加载失败。我曾经遇到过url忘记改结果本地一切正常部署到线上后样式丢失的问题排查了半天才定位到是配置里的域名没更新。改配置之前建议先备份一份_config.yml因为改动后如果生成出错可以直接换回来对比排查。改任何单项配置后都要重新执行hexo clean清缓存——hexo g——hexo s这套流程避免改了个寂寞。4.3 简单定制与不要随便DIY这两条线轻度定制是可以的比如在主题的配置文件夹里改导航栏链接、改首页展示的文章摘要长度、给自己的社交链接加上GitHub和邮箱这些都能做而且大部分主题都预留了相应字段。但这里有一条明确的警告线不要为了自认为的技术酷炫去改主题的核心逻辑文件。比如主题的布局模板Layout模板如果HTML结构不熟、CSS也不熟改了容易引发全局样式错乱。你写个人博客是为了记录和分享不是为了造一个技术上“完美”的主题框架。等文章量上来了确实觉得主题功能不够用再去换主题到时候你对自己的需求会更清楚也不容易改坏。5. 部署到GitHub Pages本地生成与远端发布的分工这是整个流程里最让人紧张、迈过去之后最轻松的一步。核心就一句话把本地生成好的静态文件推送一份到你的Pages仓库里跟手动HTML方式的区别只是步骤自动化了。5.1 配置部署信息_config.yml里的deploy字段打开主配置_config.yml找到deploy部分改成deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main要说明一下部分HEXO版本的默认分支是master但GitHub现在对新建仓库的默认分支叫main。部署之前一定先确认你的Pages仓库分支到底叫main还是master不匹配会导致推送失败。查看方法是在GitHub仓库页面左上角就有分支名。有人会问为什么要用https地址而不配置SSHhttps方式首次部署时会要求输入GitHub账号密码或令牌SSH方式需要先配置密钥。对新手来说https加令牌的方式最直观SSH更适合已经熟悉认证机制的老手。教程里先用https踩坑少。5.2 装部署插件hexo-deployer-gitHEXO默认没有部署到Git仓库的能力需要装一个插件npm install hexo-deployer-git --save不装这个插件执行hexo d会提示无法识别deploy配置或直接报git部署器的错误。这个坑非常经典配置文件里明明填好了就是因为缺插件导致部署失败。5.3 部署一次看全流程clean、generate、deploy部署流程我建议固定走这三步hexo clean hexo g hexo dhexo clean清除旧的生成缓存和静态文件hexo g重新生成完整站点hexo d调用部署插件把public目录里的内容推送至远端仓库。执行hexo d时可能会弹出GitHub身份认证窗口或在终端里提示输入用户名密码。如果你之前设置了双重认证密码框实际上需要填入令牌而不是账号密码。首次部署成功后访问https://你的用户名.github.io应该能看到和本地预览一模一样的页面。到了这一步你已经完成了从零到一的关键闭环——以后写文章只需要hexo new、写完hexo g、hexo d就能上线。5.4 为什么要严格区分hexo g和hexo s、hexo d新手经常搞混三个命令的用途hexo s只启动本地预览服务器不会把页面推上线hexo g只在本地生成静态文件hexo d才真正推送远端。日常写作时用hexo s在本地预览效果确认没问题后再hexo g加hexo d上真实部署这相当于发布前多了一层检查关卡。我是强烈建议在正式部署前养成“本地预览完再部署”的习惯。有一次我改了一篇文章手一快直接hexo d结果部署上去发现front-matter写错了页面显示异常又得重新修改、重新生成、重新部署一遍来来回回多花好几分钟。先本地看再上线上效率反而更高。6. Windows下的实测踩坑那些文档没写清楚的事最后这一节把我在Windows上跑HEXO过程中踩过的、身边同事也反复踩的坑集中拆一遍。每一条都是真实经历照着避坑能少走很多弯路。6.1 坑一终端编码问题导致中文乱码症状是hexo s跑起来后浏览器页面上的中文全变成乱码或者生成HTML里的中文显示异常。根因多半是Windows终端默认编码不是UTF-8导致HEXO读取文件时按本地代码页解析。解决方案分两层。第一层把Windows系统区域设置里的“Beta版:使用Unicode UTF-8提供全球语言支持”勾上位置在控制面板的“区域—管理—更改系统区域设置”然后重启。第二层在PowerShell里临时设置chcp 65001将终端代码页切换为UTF-8再执行hexo命令。经历过这个坑之后我直接给所有Markdown文件明确了编码为UTF-8编辑器里保存时确认编码格式基本杜绝了乱码问题。6.2 坑二npm安装依赖时出现权限或网络错误在Windows上执行npm install时可能报EPERM权限错误或网络超时。权限错误多半是因为终端没有以管理员身份运行或者Node.js安装目录的写权限受限。简单粗暴的办法是关闭杀毒软件实时防护后重试或者用管理员身份打开PowerShell再执行一次。网络超时则多半是npm默认源国内访问不稳定可以换成国内镜像源npm config set registry https://registry.npmmirror.com换源之后重新安装依赖速度会有肉眼可见的提升。6.3 坑三部署时身份验证失败伪装密码与令牌的区分执行hexo d时最常遇到的就是Username for https://github.com:提示然后输入密码后返回Authentication failed。这个“密码”其实不是GitHub登录密码而是需要去GitHub设置里生成一个Personal Access Token个人访问令牌在生成的令牌页面勾选repo权限范围复制这串令牌粘贴到密码输入框里。我最初也卡在这里试了三次登录密码都报错后来才知道启用双重认证后git操作必须用令牌。给这条踩坑记录特意留个位置是因为我身边已经有三位开发者倒在同一道坎上。配置好令牌之后可以用系统自带凭据管理器把它记住后面推送就不用反复输入。6.4 坑四分支不匹配导致部署后线上看不到内容部署成功后线上还是旧页面甚至404十有八九是分支问题。你推到了main分支但Pages服务却绑定在master分支浏览器自然加载不到新内容。去GitHub仓库的Settings——Pages设置里确认Source分支选的是你部署推送的那个分支。还有一种情况是页面文件推送到了但Pages服务没有触发重新构建。搞定方法是往仓库里随便推一个空提交比如git commit --allow-empty -m trigger pages rebuild git push或者到Pages设置页面里手动切换一下Source分支再切回来也能强制重新构建。6.5 坑五本地正常但部署后样式全丢先检查config里的url这个在前面提到过。样式文件通常是以绝对路径方式引用的如果_config.yml里的url和root配置不对浏览器从线上访问时会拿旧域名的拼接路径去找CSS文件自然全部404。排查方式在线上页面按F12打开开发者工具看Console和Network面板里的CSS文件请求地址是不是指向了错误域名。如果是改回正确url重新生成部署。这个坑容易在切换站点域名或者换电脑续写博客时遇到记一笔。6.6 打包一份Windows下的小工具箱备忘最后把我这套稳定跑了一年的HEXO环境配置放在这里供参考组件版本建议备注Node.js18.x或20.x LTS别追最新LTS最稳npm随Node.js附带可以顺带配置国内镜像源HEXO6.x或7.x太旧版本对新Node兼容差hexo-deployer-git最新版必须单独安装Git for Windows最新稳定版安装时记得加入PATH这套组合在Windows 10和Windows 11上都跑过稳定到可以放心持续使用。说到底HEXO这套东西真不难难点都在环境、编码、认证和分支这些看不见的地方。把这几座山翻过去之后日常写作流程会变得极其顺手——打开编辑器写Markdown三行命令上线整个过程不足两分钟。等你自己真跑通第一篇部署再回头看这篇教程会发现那些所谓的坑其实都不过是几步配置的事。后面如果你也想给自己的博客加个评论系统、配个站点统计、开启文章置顶以这套基础架构去打底扩展起来也会顺畅很多。 
长河君 · 2026/10/18 8:09:36 · 阅读 1.2k Windows下HEXO搭建静态博客并部署GitHub Pages全流程指南
从空仓库到第一篇博客Windows下用HEXO把博客页面真正跑起来上篇我们把GitHub Pages的仓库建好、权限理顺了但说句实话那种手动写HTML再推上去的方式撑死写两篇三篇就烦了——每篇都要套一遍完整的头部、导航、侧栏改个样式还得全局翻。所以这次直接上HEXO把本地写文章、生成静态页面、一键部署这条链路彻底打通。这篇只讲Windows环境下的实操从装环境到第一篇正式文章落地再到现在你敲完命令就能打开博客看到的完整路径。适合的读者是已经注册好GitHub账号、建好了以用户名命名的Pages仓库但卡在“不知道本地怎么搞”这一步的人。同时也劝退一种人——如果你只想原地写几篇Markdown、连版本管理都懒得碰那HEXO可能是负担留在手动HTML就行。但如果你想认真运营一个技术博客把写作、发布、回滚、主题定制都掌握在自己手里HEXO这套组合拳确实值得吃透。1. 为什么是HEXO而不是别的静态博客选型的逻辑先理清楚没接触过静态博客生成器的人第一次听HEXO可能会懵我文章明明写在本地怎么就能变成一个网站了这里面其实就两条线——本地有一条“内容生产流水线”远端有一个“静态页面托管仓库”两者之间靠生成和部署命令对接。1.1 生成器到底干了什么Markdown进去整套站点出来你写博客时主要面对的是Markdown文件它只负责记录文字、标题、列表、代码块不含任何页面骨架。HEXO这类静态生成器做的事情就是把这些Markdown文件套进预先定义好的主题模板里渲染成一整套HTML、CSS、JavaScript文件——也就是真正浏览器能看懂、能渲染的静态站点。整个过程可以类比成“印刷”Markdown是原稿主题模板是排版版式生成命令按下之后所有文章被统一排版成批量印刷品。传统动态博客比如WordPress是“读者每一次访问服务端都现场组装一次页面”而HEXO是“组装动作提前在本地完成服务端只负责把现成的文件原样端出去”。这两者最直观的差异就是速度纯静态文件部署出去几乎不用等服务器运算打开速度天然就快。而且静态站点还有个隐性好处——不容易被入侵。没有动态脚本在服务器上运行攻击面小了一大圈。对个人博客来说安全性、速度、可维护性这三样静态生成方案基本都占齐了。1.2 HEXO在同类工具里的位置Node.js生态是它最大的底气静态博客生成器其实有不少选择比如JekyllRuby生态、HugoGo生态、VuePressVue生态等。HEXO能成为很多人的入门首选主要靠两点一是Node.js生态普及度高前端开发者几乎都有现成环境装起来没有额外心智负担二是主题和插件数量可观几百个主题里总能挑到顺眼的想要评论、搜索、站点统计都有对应插件。还有个很实际的原因是文档和中文社区资源丰富。对国内开发者来说遇到问题搜一下能搜到大量现成的踩坑记录这种“社区成熟度”在我眼里比某些工具本身的功能亮点还值钱。你在Windows下遇到个编码问题很可能在你之前已经有几十个人问过、答过复制答案就能解决。1.3 Windows用户需要提前建立的三个心态第一命令行不是洪水猛兽。HEXO的核心操作就那几条命令hexo init初始化、hexo new写新文章、hexo g生成页面、hexo s本地预览、hexo d部署上线。把它们当成“跟电脑对话的固定短语”就行不需要懂底层原理也能玩得转。第二Node.js环境是必须跨过去的门槛。后面会详细讲这里先打个底HEXO基于Node.js运行没有它一切无从谈起。有不少人卡在安装环节就放弃实在可惜——装环境其实跟在Windows上装任何软件没有本质区别只是多了一个“环境变量”概念需要理解。第三版本兼容性要放在心上。Node.js版本太新或太旧都可能导致HEXO安装报错这跟“越新越好”的直觉相反。我用的是Node.js的LTS版本长期支持版配合HEXO 6.x和7.x都跑过整体很稳定。建议你装LTS别追新追新是给自己找坑。2. 开工前的准备Node.js与Git的环境坑位没环境就跑不了HEXO但装环境本身也有讲究。很多人栽在“明明装好了命令却提示找不到”这一节把这些坑提前填平。2.1 Node.js安装的版本选择与验证方式去官网下载LTS版本安装包。选版本的时候注意查看HEXO官方文档中对Node.js版本范围的要求不同版本的HEXO对Node版本的要求有差异。保守做法是选当前时间的LTS版本比如我这边用Node.js 18.x或20.x都没有问题。安装过程基本是“下一步下一步”但有两个细节容易被忽略安装路径不要带空格和中文。某些工具对路径解析有兼容问题干脆从一开始就把路径设置成全英文简单目录比如D:\Nodejs。装完之后要验证是否真正生效。打开一个新的PowerShell窗口不是安装前打开的那个旧窗口执行node -v npm -v如果两个命令都能输出版本号说明Node.js和随附的npm都装好了。如果提示“无法识别”大概率是环境变量没刷新——重开终端基本就能解决。2.2 Git安装与“命令存在于安装目录但终端不认”的经典问题HEXO部署到GitHub Pages需要调用Git完成推送所以Git也是必装项。同样注意路径全英文、安装选项里建议开启“从命令行使用Git”的选项这样PowerShell里才能直接用git命令。我见过很多开发者在终端里执行git却提示找不到命令但Git明明装好了。原因多半是安装时没有勾选把Git加入PATH的选项或者安装后没有重新打开终端。遇到这种情况重新运行Git安装包在调整PATH的步骤里选择“推荐设置”然后重新打开终端验证git --version2.3 提前配好Git身份信息部署时少踩身份认证的坑初始化和后续部署都用得着Git的用户信息建议安装完Git就先配好git config --global user.name 你的用户名 git config --global user.email 你的邮箱注意这里的用户名和邮箱不一定非要用GitHub上那个但建议保持一致这样提交记录里显示的作者信息是认得的后面排查问题也少一层迷惑。尤其邮箱GitHub要求邮箱验证过才能正确关联提交记录。这个环节看起来跟HEXO没什么直接关系实际上等部署阶段真出了身份认证问题再回头配就很绕。提前配好的意义是在“部署那一步”之前把变量清零。3. 从初始化站点到第一篇文档落地的完整路径环境备齐后核心流程正式启动。这一节从建站命令开始把每一步该干什么、命令会产生什么效果讲清楚。3.1 hexo init初始化一个博客骨架先在本地创建一个专门放博客的目录比如D:\myblog进入该目录后执行npm install hexo-cli -g hexo init .这句命令的逻辑是先全局安装HEXO的命令行工具然后在当前目录初始化博客骨架。init会自动拉取HEXO的基础模板包括配置文件_config.yml、主题目录themes、文章目录source/_posts以及默认的hello world文章。初始化完成后结构会是这样的_config.yml站点主配置文件。站点名称、作者信息、语言、部署配置等都写在这里。source/_posts/存放Markdown文章。themes/主题文件夹。node_modules/项目依赖模块。package.json项目依赖清单。初始化完成后建议立刻补装依赖npm install如果不执行这一步后面生成页面时大概率报缺模块的错误。3.2 本地预览把“看不见的站点”先跑起来靠hexo generate简写hexo g生成的静态文件其实可以直接扔到任意静态服务器上跑。但本地开发阶段我们更常用的是内置的开发服务器hexo server执行后终端会输出类似http://localhost:4000的地址在浏览器里打开就能看到你的博客框架和默认的hello world页面。这个本地预览服务很实用的一点是支持热更新——你改完Markdown文件刷新一下浏览器就能看到变化不用重新手动生成。3.3 真正写一篇文章hexo new的产物是什么默认的hello world只是试手用的真正的写作得靠新建文章hexo new 我的第一篇文章执行后会生成source/_posts/我的第一篇文章.md用任意文本编辑器打开会看到头部有一段YAML格式的front-matter--- title: 我的第一篇文章 date: 2024-01-01 12:00:00 tags: ---这里有一点经验之谈front-matter里的title字段可以留空直接设置为文件名对应的标题。但更推荐在文件里维护一个清晰的中文标题因为URL默认使用文件路径和文件名如果文件名叫中文或者很随意网址会很长很难看。我的习惯是文件名用英文或日期加英文而在front-matter中给出中文标题这样搜索引擎和阅读体验都更好。比如hexo new post/2024-01-01-welcome这样生成的路径会更干净而页面显示标题远处由front-matter里的title决定。3.4 Markdown写作的基本细节从“能写”到“想好好写”HEXO的正文内容就是标准Markdown#表示一级标题、##表示二级标题 包裹代码块插入图片。这些基础语法不展开讲了这里想强调两个HEXO场景下的特殊细节第一如果文章里嵌代码块一定要指定代码语言。比如写JavaScript片段就写javascript console.log(hello world); 代码高亮基于语言标识符。不写的后果是代码块缺少语法高亮阅读体验差一大截。代码块里的三个反引号也要留意如果代码内容本身含有三反引号需要在语法中处理否则会出现解析错乱。第二图片资源管理。HEXO默认情况下文章里的图片需要手工放到source/images目录并在Markdown里引用网络路径。本地路径直接写相对路径比较容易被生成器处理出错我的习惯是用一个图床服务或者把图片放到项目目录里后再用相对路径另外一个更省心的方法是把_config.yml里的post_asset_folder设置为true这样hexo new会为每篇文章单独建一个同名文件夹图片放进去之后用相对路径引用即可。hexo new 带图片的测试文章开启post_asset_folder后执行以上命令会在_posts下生成一个同名目录把图片丢进去然后用引用生成的页面图片路径不会错。4. 主题、配置与内容展示让页面别太素也别乱改HEXO默认主题非常朴素很多人第一眼看到会觉得“这也能叫博客”别急换主题和参数配置都在这一步完成。4.1 换主题的正确姿势Git clone的目录归属别放错到HEXO的官方主题库挑一个顺眼的主题假设叫某主题名称安装方式通常是git clone https://git.example.com/themes/某主题.git themes/某主题关键点是克隆到themes目录下而不是随便放到桌面或下载文件夹。主题目录的释放位置错了会导致HEXO完全找不到它。装好后修改主配置theme: 某主题然后重新hexo g生成、hexo s预览看效果。换主题这事我想多说两句很多人一上来就追求功能花哨的主题折腾两星期主题配置文章一篇没写。这是本末倒置的。主题能用、顺眼、不花哨就暂时够了写作内容才是博客的核心资产。我自己的博客换过三回主题每次换主题都要重新调整样式和插件时间成本极高。建议新人在最初的三五个月里锁死一个主流主题不动专心写内容。4.2 配置文件里的高频字段改之前先备份HEXO的主配置_config.yml里几个高频字段title: 博客标题 author: 作者名 language: zh-CN url: https://你的用户名.github.io其中url字段要特别注意。如果这里不填或填错后面部署后浏览器地址栏的链接可能指向旧域名导致页面能打开但CSS和图片全部加载失败。我曾经遇到过url忘记改结果本地一切正常部署到线上后样式丢失的问题排查了半天才定位到是配置里的域名没更新。改配置之前建议先备份一份_config.yml因为改动后如果生成出错可以直接换回来对比排查。改任何单项配置后都要重新执行hexo clean清缓存——hexo g——hexo s这套流程避免改了个寂寞。4.3 简单定制与不要随便DIY这两条线轻度定制是可以的比如在主题的配置文件夹里改导航栏链接、改首页展示的文章摘要长度、给自己的社交链接加上GitHub和邮箱这些都能做而且大部分主题都预留了相应字段。但这里有一条明确的警告线不要为了自认为的技术酷炫去改主题的核心逻辑文件。比如主题的布局模板Layout模板如果HTML结构不熟、CSS也不熟改了容易引发全局样式错乱。你写个人博客是为了记录和分享不是为了造一个技术上“完美”的主题框架。等文章量上来了确实觉得主题功能不够用再去换主题到时候你对自己的需求会更清楚也不容易改坏。5. 部署到GitHub Pages本地生成与远端发布的分工这是整个流程里最让人紧张、迈过去之后最轻松的一步。核心就一句话把本地生成好的静态文件推送一份到你的Pages仓库里跟手动HTML方式的区别只是步骤自动化了。5.1 配置部署信息_config.yml里的deploy字段打开主配置_config.yml找到deploy部分改成deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main要说明一下部分HEXO版本的默认分支是master但GitHub现在对新建仓库的默认分支叫main。部署之前一定先确认你的Pages仓库分支到底叫main还是master不匹配会导致推送失败。查看方法是在GitHub仓库页面左上角就有分支名。有人会问为什么要用https地址而不配置SSHhttps方式首次部署时会要求输入GitHub账号密码或令牌SSH方式需要先配置密钥。对新手来说https加令牌的方式最直观SSH更适合已经熟悉认证机制的老手。教程里先用https踩坑少。5.2 装部署插件hexo-deployer-gitHEXO默认没有部署到Git仓库的能力需要装一个插件npm install hexo-deployer-git --save不装这个插件执行hexo d会提示无法识别deploy配置或直接报git部署器的错误。这个坑非常经典配置文件里明明填好了就是因为缺插件导致部署失败。5.3 部署一次看全流程clean、generate、deploy部署流程我建议固定走这三步hexo clean hexo g hexo dhexo clean清除旧的生成缓存和静态文件hexo g重新生成完整站点hexo d调用部署插件把public目录里的内容推送至远端仓库。执行hexo d时可能会弹出GitHub身份认证窗口或在终端里提示输入用户名密码。如果你之前设置了双重认证密码框实际上需要填入令牌而不是账号密码。首次部署成功后访问https://你的用户名.github.io应该能看到和本地预览一模一样的页面。到了这一步你已经完成了从零到一的关键闭环——以后写文章只需要hexo new、写完hexo g、hexo d就能上线。5.4 为什么要严格区分hexo g和hexo s、hexo d新手经常搞混三个命令的用途hexo s只启动本地预览服务器不会把页面推上线hexo g只在本地生成静态文件hexo d才真正推送远端。日常写作时用hexo s在本地预览效果确认没问题后再hexo g加hexo d上真实部署这相当于发布前多了一层检查关卡。我是强烈建议在正式部署前养成“本地预览完再部署”的习惯。有一次我改了一篇文章手一快直接hexo d结果部署上去发现front-matter写错了页面显示异常又得重新修改、重新生成、重新部署一遍来来回回多花好几分钟。先本地看再上线上效率反而更高。6. Windows下的实测踩坑那些文档没写清楚的事最后这一节把我在Windows上跑HEXO过程中踩过的、身边同事也反复踩的坑集中拆一遍。每一条都是真实经历照着避坑能少走很多弯路。6.1 坑一终端编码问题导致中文乱码症状是hexo s跑起来后浏览器页面上的中文全变成乱码或者生成HTML里的中文显示异常。根因多半是Windows终端默认编码不是UTF-8导致HEXO读取文件时按本地代码页解析。解决方案分两层。第一层把Windows系统区域设置里的“Beta版:使用Unicode UTF-8提供全球语言支持”勾上位置在控制面板的“区域—管理—更改系统区域设置”然后重启。第二层在PowerShell里临时设置chcp 65001将终端代码页切换为UTF-8再执行hexo命令。经历过这个坑之后我直接给所有Markdown文件明确了编码为UTF-8编辑器里保存时确认编码格式基本杜绝了乱码问题。6.2 坑二npm安装依赖时出现权限或网络错误在Windows上执行npm install时可能报EPERM权限错误或网络超时。权限错误多半是因为终端没有以管理员身份运行或者Node.js安装目录的写权限受限。简单粗暴的办法是关闭杀毒软件实时防护后重试或者用管理员身份打开PowerShell再执行一次。网络超时则多半是npm默认源国内访问不稳定可以换成国内镜像源npm config set registry https://registry.npmmirror.com换源之后重新安装依赖速度会有肉眼可见的提升。6.3 坑三部署时身份验证失败伪装密码与令牌的区分执行hexo d时最常遇到的就是Username for https://github.com:提示然后输入密码后返回Authentication failed。这个“密码”其实不是GitHub登录密码而是需要去GitHub设置里生成一个Personal Access Token个人访问令牌在生成的令牌页面勾选repo权限范围复制这串令牌粘贴到密码输入框里。我最初也卡在这里试了三次登录密码都报错后来才知道启用双重认证后git操作必须用令牌。给这条踩坑记录特意留个位置是因为我身边已经有三位开发者倒在同一道坎上。配置好令牌之后可以用系统自带凭据管理器把它记住后面推送就不用反复输入。6.4 坑四分支不匹配导致部署后线上看不到内容部署成功后线上还是旧页面甚至404十有八九是分支问题。你推到了main分支但Pages服务却绑定在master分支浏览器自然加载不到新内容。去GitHub仓库的Settings——Pages设置里确认Source分支选的是你部署推送的那个分支。还有一种情况是页面文件推送到了但Pages服务没有触发重新构建。搞定方法是往仓库里随便推一个空提交比如git commit --allow-empty -m trigger pages rebuild git push或者到Pages设置页面里手动切换一下Source分支再切回来也能强制重新构建。6.5 坑五本地正常但部署后样式全丢先检查config里的url这个在前面提到过。样式文件通常是以绝对路径方式引用的如果_config.yml里的url和root配置不对浏览器从线上访问时会拿旧域名的拼接路径去找CSS文件自然全部404。排查方式在线上页面按F12打开开发者工具看Console和Network面板里的CSS文件请求地址是不是指向了错误域名。如果是改回正确url重新生成部署。这个坑容易在切换站点域名或者换电脑续写博客时遇到记一笔。6.6 打包一份Windows下的小工具箱备忘最后把我这套稳定跑了一年的HEXO环境配置放在这里供参考组件版本建议备注Node.js18.x或20.x LTS别追最新LTS最稳npm随Node.js附带可以顺带配置国内镜像源HEXO6.x或7.x太旧版本对新Node兼容差hexo-deployer-git最新版必须单独安装Git for Windows最新稳定版安装时记得加入PATH这套组合在Windows 10和Windows 11上都跑过稳定到可以放心持续使用。说到底HEXO这套东西真不难难点都在环境、编码、认证和分支这些看不见的地方。把这几座山翻过去之后日常写作流程会变得极其顺手——打开编辑器写Markdown三行命令上线整个过程不足两分钟。等你自己真跑通第一篇部署再回头看这篇教程会发现那些所谓的坑其实都不过是几步配置的事。后面如果你也想给自己的博客加个评论系统、配个站点统计、开启文章置顶以这套基础架构去打底扩展起来也会顺畅很多。