Hexo博客安装这件事我已经来回折腾过好几遍了。每次换电脑、帮朋友搭博客都会把“装Node.js、装Git、装Hexo、部署上线”这套流程重走一遍。很多人一听到“命令行”“部署”就发怵实际上只要你把每一步的顺序搞清楚Hexo博客安装也就是三个大环节环境准备、初始化、发布。这篇教程我会用尽量啰嗦的方式把每一步为什么要做、怎么做、做完怎么验证都写清楚哪怕你是第一次接触Windows命令行也能跟着走完最后拥有一个可以通过公网访问的个人博客。1. 环境准备把Node.js和Git装好1.1 为什么要先装Node.js和GitHexo是一个基于Node.js的静态博客框架。你可以把它理解成一台“文章加工机器”你给它喂Markdown格式的文章它自动帮你生成一堆HTML、CSS、JS静态文件这些文件放到任意Web服务器上就能被访问。所以机器本身要能跑起来就必须先装Node.js。Node.js是Hexo的运行时环境Hexo所有的命令都是通过Node.js执行的。Git又是什么Hexo生成的静态页面需要发布到网上的某个托管平台目前最主流的是GitHub Pages。Git就是用来把本地生成的文件“推”到GitHub上去的工具。即使你不想用GitHub想自己买服务器部署Git也会帮你做版本管理写博客内容多一份安全保障。安装顺序没太多讲究但我习惯先装Git再装Node.js最后装Hexo。原因很简单后面初始化主题、拉取模板都需要用到GitNode.js装完顺便把npm也带来了这是装Hexo CLI的工具。1.2 Node.js保姆级安装步骤去Node.js官网 nodejs.org 下载安装包。页面上有两个大按钮左边是LTS长期支持版右边是Current当前版。个人博客用LTS就好稳定第一不要图新功能。Windows安装包是一个.msi文件双击打开后一路“Next”。有几个点要注意安装路径建议保持默认比如C:\Program Files\nodejs\这样PATH环境变量会自动配置好到“Custom Setup”那一步时确保“Add to PATH”是选中的默认就是选中别手滑取消装完后系统会重启一下终端或者电脑保险起见建议重启一次。macOS用户下载.pkg文件同样一路继续。装完以后打开终端Windows上是CMD或PowerShell输入node -v npm -v能看到类似v20.11.0和10.2.4这样的版本号说明Node.js和npm都装好了。注意如果提示“node不是内部或外部命令”绝大多数情况是PATH没配好。Windows用户可以去“设置 - 系统 - 关于 - 高级系统设置 - 环境变量”把C:\Program Files\nodejs\手动加到Path里。1.3 Git安装与基础配置Git的下载地址是 git-scm.com 同样选Windows或macOS对应的安装包。Windows用户安装时注意一路Next时在“Select Components”页面保持默认可以额外勾上“Git Bash Here”“Default editor”建议选“Use Visual Studio Code”后面修改配置文件会很方便“Adjusting your PATH environment”那一项选“Git from the command line and also from 3rd-party software”默认第二项就行。装完打开终端输入git --version能输出版本号就说明安装成功。这时候还需要配置一下身份信息因为Git提交代码时要记录“谁提交的”git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的邮箱建议和GitHub注册邮箱保持一致后面部署时会少很多麻烦。验证一下配置是否写入git config --global user.name git config --global user.email会把刚才填的内容原样打印出来。这一步很多人会跳过直到部署时报错“Please tell me who you are”才回来补早做早安心。2. 安装Hexo并初始化博客2.1 安装Hexo命令行工具Node.js装好后npm就自带了一个全局安装命令。打开终端执行npm install -g hexo-cli-g表示全局安装这样你在任何目录下都能直接使用hexo命令。安装过程会有一段进度条如果没有任何报错输入hexo version会显示类似hexo-cli: 4.3.2的版本信息。这里有一个我在Windows上踩过的坑如果你不是在管理员权限下打开终端npm可能因为没有C盘写入权限而报错。解决办法不是去改权限而是右键点击终端选“以管理员身份运行”再执行一次安装命令。npm下载速度慢的话可以配置一下国内npm源这是常规操作npm config set registry https://registry.npmmirror.com配置完再执行安装命令速度会快很多。这个修改只影响npm包的下载源不影响你博客本身。2.2 初始化博客目录选一个你喜欢的本地目录比如D:\blog然后执行mkdir blog cd blog hexo inithexo init会自动拉取Hexo基础模板并生成一套默认的博客文件结构。可能有人会问为什么是空目录因为Hexo要求初始化的目标目录尽量是空的否则可能覆盖已有文件。初始化完成后继续执行npm install这条命令会安装博客依赖的所有npm包。等它跑完你的博客基本就成型了。使用dirWindows或lsmacOS/Linux查看目录你会看到这些核心目录目录/文件作用_config.yml博客全局配置文件站点名称、主题、部署地址都在这里package.json记录依赖包信息scaffolds/文章模板目录新建文章时套用source/存放Markdown文章、图片等源文件source/_posts/博客文章所在地themes/存放主题的目录public/生成后的静态网页之后部署的就是这个目录提示public/目录每次运行hexo generate都会被重新生成不要手动修改里面的文件否则下次生成时会被覆盖。2.3 启动本地预览验证效果现在先不急着写文章先把博客跑起来看看hexo server终端会提示Hexo is running at http://localhost:4000。打开浏览器访问http://localhost:4000你会看到Hexo默认的hello world页面。看到页面就说明整个安装流程已经打通了。如果端口4000被占用终端会报错EADDRINUSE这时候可以用hexo server -p 4001换个端口。本地预览属于开发环境只会把博客跑到本地外网访问不到你可以放心折腾。后续每次本地预览我习惯先执行hexo clean再hexo server。hexo clean会清空public/目录和缓存防止旧的静态文件残留导致页面不更新。3. 写文章与日常管理3.1 用hexo new命令创建第一篇文章博客环境跑通后来写第一篇文章。终端执行hexo new 我的第一篇博客Hexo会根据scaffolds/post.md模板在source/_posts/下生成一个我的第一篇博客.md文件。用任意文本编辑器打开它会看到类似这样的内容--- title: 我的第一篇博客 date: 2025-03-01 10:00:00 tags: ---这段被---包起来的内容叫Front Matter是文章元信息。title是文章标题date是发布时间tags是标签。可以继续添加categories来分类--- title: 我的第一篇博客 date: 2025-03-01 10:00:00 tags: - 随笔 categories: - 生活 ---写完后在终端重新执行hexo server刷新浏览器你就能在首页看到这篇文章。文章正文直接用标准Markdown语法写在Front Matter下面比如# 第一次写博客 今天终于把博客搭起来了很开心。 - 第一件事 - 第二件事3.2 Front Matter与Markdown写作规范Front Matter字段看着简单用起来有几个小细节会影响页面展示。title如果标题里含英文冒号记得用引号包住比如title: 浏览器从入门到放弃否则YAML解析会出错。date建议保留默认生成的时间这样文章列表才能按时间排序。tags和categories支持写多个缩进两个空格再加-。注意Hexo的分类和标签不同分类有层级关系标签只是平级的文章关键词。comments: true/false用来控制单篇文章是否开启评论默认开启。sticky: 1这是部分主题支持的置顶参数数值越大越靠前。再聊图片。写博客难免要贴图最简单的方法是把图片放到source/images/目录下然后在Markdown里引用如果希望图片和文章放在一起可以用Hexo的“资源文件夹”功能。先在_config.yml里设置post_asset_folder: true然后执行hexo new 带图文章Hexo会自动创建一个同名文件夹把图片丢进去Markdown里相对路径引用就行。注意修改这个配置后最好重启一下hexo server再写文章。3.3 用VSCode提升写作效率写Markdown文章我强烈推荐Visual Studio Code。官网下载安装后再装两个插件Markdown All in One和Markdown Preview Enhanced。前者支持快捷键生成Markdown语法后者可以在编辑器里实时预览排版效果。VSCode里操作很简单打开blog文件夹左侧找到source/_posts/下的文章直接编辑右侧打开预览面板边写边看格式。写完后不需要手动拷贝到浏览器刷新只要终端里还跑着hexo server保存文件后浏览器刷新页面就能看到最新效果。Word、WPS这类富文本编辑器不适合写Hexo博客因为它们的排版本质上是给Word文档用的粘贴到Markdown里会带一堆乱七八糟的样式。Markdown的“所见即所得”需要你适应一下其实习惯以后写作会特别顺。4. 站点配置与主题美化4.1 修改全局配置文件_config.yml博客根目录下的_config.yml是整个站点的总控制台。用VSCode打开它重点看这几个字段title: My Blog subtitle: 我的个人博客 description: 记录技术、生活和思考 author: Demo language: zh-CN timezone: Asia/Shanghaititle站点名称会显示在浏览器标签和页面顶部subtitle副标题会显示在主页标题下方description站点描述会被搜索引擎抓取author作者名会显示在文章页的版权信息里language设置成zh-CN很多主题会切换为中文界面timezone设置成Asia/Shanghai文章发布和显示的时间才会是东八区还有一个重要字段是url本地预览时不用管但部署上线后必须改成你的最终访问地址比如https://username.github.io否则站点地图、分享链接这些依赖url的功能会算错路径。注意编辑_config.yml时冒号后面一定要有英文空格比如title: My Blog写成了title:My Blog会导致解析失败博客直接报错。这是新手最容易碰到的YAML格式问题。改完保存刷新浏览器就能看到生效了。如果没生效先hexo clean再hexo server。4.2 安装NexT主题Hexo默认主题很朴素大多数人会换一个。我常用的是NexT主题它有几种风格Mist、Muse、Gemini等简洁且文档完善。安装方式是在博客根目录执行npm install hexo-theme-next然后修改_config.ymltheme: next保存后刷新页面主题就换过来了。NexT的配置在themes/next/_config.yml里注意不要和根目录的_config.yml搞混。我经常看到有人把主题配置写到根目录结果怎么改都不生效。主题配置里常用的几个menu设置顶部导航菜单比如home: /、archives: /archives、tags: /tags想显示哪个取消注释即可。avatar设置头像图片地址可以放一张图到source/uploads/avatar.jpg然后填写/uploads/avatar.jpg。social添加社交链接比如GitHub、Twitter、邮箱等。scheme切换主题风格NexT默认是Scheme Muse你可以改成Scheme Mist试试。每次修改主题配置后同样要重启本地服务才能看到变化。4.3 给博客加几个实用插件博客不能只有文章列表最好还有归档、标签页。创建这些页面需要执行hexo new page tags hexo new page categories然后在source/tags/index.md和source/categories/index.md的Front Matter中填写type: tags ---这样导航菜单里的tags和categories页面就能正常打开了。再装两个常用插件npm install hexo-generator-sitemap --save npm install hexo-generator-feed --save前者生成sitemap.xml方便搜索引擎收录后者生成RSS订阅文件方便读者订阅你的博客。安装后不需要额外配置重新生成静态文件时就会出现在public/目录下。如果你喜欢文章中显示“阅读量”、“字数统计”可以装hexo-word-counter插件按它的文档在主题配置里开启对应模块。插件别贪多装一个就测试一个避免相互冲突。5. 部署到GitHub Pages5.1 创建GitHub仓库并配置SSH Key本地博客做好后下一步就是发布到网上。使用GitHub Pages免费托管静态博客是很多人的选择因为不需要买服务器。先在GitHub上创建一个仓库仓库名必须用你的用户名.github.io这种格式比如用户名是demo仓库名就是demo.github.io。这是GitHub Pages的特殊规则名字不对页面无法通过这个域名访问。然后你得让本地Git能认证到你的GitHub账号。推荐配置SSH Key这样以后部署不用反复输密码。打开终端执行ssh-keygen -t rsa -b 4096 -C 你的邮箱一路回车生成默认文件。命令执行完会有提示找到公钥路径一般是C:\Users\你的用户名\.ssh\id_rsa.pub。用文本编辑器打开这个文件复制全部内容。登录GitHub进入Settings - SSH and GPG keys - New SSH key把公钥粘贴进去保存。然后在终端测试ssh -T gitgithub.com看到Hi username! Youve successfully authenticated这样的提示说明认证成功。提示SSH Key属于个人凭据id_rsa私钥绝对不能泄露也不要放到博客仓库里。传到网上的是.pub结尾的公钥。5.2 安装部署插件并配置deploy参数Hexo默认不带Git部署功能需要先安装插件。在博客根目录执行npm install hexo-deployer-git --save然后修改根目录_config.yml在文件末尾添加deploy: type: git repo: gitgithub.com:用户名/用户名.github.io.git branch: mainrepo改成你自己的仓库SSH地址。在GitHub仓库首页点“Code - SSH”可以复制到这个地址。注意仓库分支名老仓库可能是master新建的默认是main保持一致。配置好后执行hexo clean hexo generate hexo deploy也可以连着写hexo clean hexo generate hexo deploy。部署过程会有进度输出最后提示Deploy done。这时打开浏览器访问https://用户名.github.io就能看到你的博客了。刚部署完可能等一两分钟才生效别急着刷新几十次。5.3 绑定自定义域名如果你有自己的域名想让它指向博客可以到域名服务商那里添加一条CNAME解析记录主机记录填或www记录值填用户名.github.io。然后手动在source/目录下新建一个名为CNAME的文件内容只写一行你的域名比如blog.example.com重新hexo clean hexo generate hexo deploy。因为source/下的文件会被原样拷贝到public/所以部署后GitHub Pages能识别CNAME文件这样域名就绑定了。同时记得把根目录_config.yml的url改成你的自定义域名比如https://blog.example.com不然站点地图里的链接域名还是github.io。6. 常见问题排查与避坑指南6.1 命令报错、端口占用、修改不生效我见过最多的几个问题hexo : 无法加载文件 ... 因为在此系统上禁止运行脚本这是Windows PowerShell执行策略限制用管理员身份打开PowerShell执行Set-ExecutionPolicy RemoteSigned选Y确认。EADDRINUSE: address already in use 4000端口被占用了换端口启动就好hexo server -p 4001。修改主题配置后页面没有变化执行hexo clean重新hexo server。写文章后浏览器看不到先确认文章保存在source/_posts/文件名以.md结尾并且不是以~$开头的临时文件。6.2 部署后页面空白或404部署到GitHub后打开是404常见原因有三个仓库名不是用户名.github.io的格式GitHub Pages不会为这种仓库自动开设主页部署分支不是main或master在GitHub仓库Settings - Pages里可以确认并修改发布分支部署时hexo generate失败public/目录只有部分内容被推上去。如果本地预览正常、线上404多半是deploy配置的repo地址或分支名写错了。还有一种情况是GitHub Pages内容更新有延迟刚部署完访问可能不是最新版本过5分钟再看。如果一直404回到本地跑hexo server确认页面正常再排查线上配置。6.3 图片加载失败与路径问题本地预览图片正常部署后图片裂了几乎都是路径问题。我建议统一使用绝对路径写图片比如图片放在source/images/blog/1.png文章中写生成后public/下会有对应的images目录。如果你启用了post_asset_folder又用了主题自带的图片功能那就严格按主题文档的写法来。改了图片路径后hexo clean是必须的否则旧的静态文件会和新文件混在一起出现“改了图片但页面没换”的错觉。6.4 主题升级与其他小坑如果你用NexT这类基于npm安装的主题升级时注意themes/next/_config.yml会被覆盖所以自定义内容一定要提前备份。我的习惯是把主题的配置文件复制到source/_data/next.yml然后在主题配置里开启override这样升级主题时自定义配置不会丢。这个方案NexT官方文档有详细说明照着做就行。另外每次从旧电脑迁移博客一定要把整个blog目录都拷贝过去包括隐藏的.github、.deploy_git如果有的话别只复制source和_config.yml否则依赖包和主题文件不全新电脑跑不起来。最后说一点个人体会博客框架再折腾也只是工具。Hexo安装这篇教程能帮你迈出第一步但真正有价值的是你开始写文章并且能持续写下去。我见过太多人花了一整天部署好博客然后只发了第一篇“Hello World”就再也没打开过。如果哪天你想放弃试着别去研究主题和插件先把一篇不完美的文章发出来你会发现写博客的乐趣其实比调博客大得多。