Hexo博客部署全攻略

超详细Hexo博客部署全攻略：从Git配置到多平台上线（附常见错误解决方案）

最近帮三个朋友搭Hexo博客，发现新手踩坑的地方高度重合：要么Node.js和Git环境配不对，要么Git和GitHub连不上，要么部署完访问是404。正好我上周重装系统后完整走了一遍流程，干脆把全步骤+避坑指南整理出来，Mac、Windows、Linux三大平台都覆盖，每个环节都标了“新手易错点”和“解决办法”，亲测跟着走能一次成功。

一、先搞懂：为什么选Hexo？新手需要知道的基础认知

很多新手上来就装软件，连Hexo是啥都没搞懂，后面出问题更懵。先花2分钟理清楚核心逻辑：

Hexo是静态博客框架，简单说就是：你用Markdown写文章，Hexo能把这些文章转换成静态HTML页面（加载速度比动态博客快很多）；然后通过Git把这些静态页面部署到GitHub Pages、Gitee Pages等平台，就能实现“免费域名+免费空间”的个人博客上线。

核心优势：轻量（本地启动秒开）、易定制（海量主题）、零成本部署（不用买服务器），适合程序员、学生或想折腾个人博客的小伙伴。

本次目标：完成“本地环境搭建→Git配置→Hexo初始化→主题配置→远程部署”全流程，最终实现通过GitHub域名访问自己的博客。

二、全平台通用：先装对核心依赖（Node.js + Git）

Hexo运行依赖Node.js（提供运行环境），部署依赖Git（连接远程仓库）。这一步是基础中的基础，环境错了后面全白搭。

2.1 安装Node.js（LTS版最稳）

Hexo对Node.js版本有要求（建议v14及以上，v18 LTS最佳），千万别装最新的“Current”版，可能有兼容性问题。

• Mac平台（两种方式）：
  方式一（小白首选）：打开Node.js官网，点击“LTS”版本的“macOS Installer”下载（约50MB），双击后拖到应用程序文件夹，全程点“继续”即可。方式二（程序员首选，用Homebrew）：如果没装Homebrew，先在终端输入/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装，然后输入brew install node，等待安装完成。

• Windows平台：
  打开Node.js官网，下载“LTS”版本的“Windows Installer”（32位选x86，64位选x64，不清楚系统位数的话，右键“此电脑”→“属性”查看）。安装时必须勾选“Add Node.js to PATH”（自动配置环境变量，新手千万别忘），其他步骤默认下一步，最后点“Finish”。

• Linux平台（以Ubuntu/CentOS为例）：
  Ubuntu：终端依次输入sudo apt update（更新软件源）、sudo apt install nodejs npm（安装Node.js和npm）。CentOS：终端依次输入sudo yum update、sudo yum install nodejs npm。

新手易错点1：安装后输入node -v提示“不是内部或外部命令”

解决办法：这是环境变量没配置好。Windows用户重新运行安装包，确保勾选“Add to PATH”；Mac/Linux用户关闭终端重新打开，或输入source ~/.bash_profile刷新环境变量。如果还是不行，手动配置环境变量（具体步骤可搜“XX系统 Node.js 环境变量配置”）。

验证安装：打开终端（Mac/Linux）或CMD/PowerShell（Windows），输入node -v和npm -v，能显示版本号（如v18.17.0）就是成功了。

2.2 安装Git（部署的关键）

Git是版本控制工具，用来把本地Hexo生成的页面同步到GitHub。安装时重点注意环境变量和编辑器配置。

• Mac平台：
  方式一（系统自带，版本较旧）：打开终端输入git --version，会提示“是否安装Command Line Tools”，点“安装”即可（约100MB）。方式二（装新版）：用Homebrew输入brew install git，或去Git官网下载dmg安装包，双击安装。

• Windows平台（重点注意步骤）：
  1. 去Git官网下载Windows安装包，双击运行；2. 选择安装路径（默认C盘即可，别含中文）；3. 组件选择默认，下一步；4. 关键步骤：“Adjusting your PATH environment”选“Git from the command line and also from 3rd-party software”（全环境可用，新手必选）；5. 默认编辑器：建议选“Use Visual Studio Code as Git’s default editor”（如果装了VS Code），没装就选默认的Vim；6. 后续步骤默认下一步，最后点“Install”。

• Linux平台：
  Ubuntu：sudo apt install git；CentOS：sudo yum install git。

新手易错点2：Windows下输入git提示“不是内部命令”

解决办法：安装时没选对PATH选项。重新运行安装包，到“Adjusting your PATH environment”步骤选对选项；或手动把Git的bin目录（如C:\Program Files\Git\bin）添加到系统环境变量的“Path”中。

验证安装：终端输入git --version，显示版本号（如git version 2.42.0）即为成功。

三、核心配置：Git连接GitHub（全平台通用，必看避坑）

这一步是部署的核心，很多人卡在这里：要么SSH密钥生成错，要么GitHub添加密钥格式不对，导致后面部署时“权限被拒”。全程用终端（Mac/Linux）或Git Bash（Windows，安装Git后桌面右键会有）操作。

3.1 第一步：配置Git用户信息（和GitHub绑定）

输入以下两条命令，把引号里的内容替换成自己的GitHub用户名和注册邮箱（必须一致，否则GitHub不认）：

git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"

验证：输入git config --global --list，能看到刚才配置的name和email就是对的。

新手易错点3：用户名和邮箱填错

解决办法：重新输入上面两条命令覆盖即可，–global参数表示全局配置，一次改完所有项目生效。

3.2 第二步：生成SSH密钥（建立信任连接）

SSH密钥是本地和GitHub的“通行证”，有了它不用每次部署都输密码。

终端输入以下命令，直接按3次回车（不要输密码，新手容易画蛇添足输密码导致后面出错）：

ssh-keygen -t ed25519 -C "你的GitHub注册邮箱"

如果系统不支持ed25519算法（老系统可能出现），换这条命令：

ssh-keygen -t rsa -b 4096 -C "你的GitHub注册邮箱"

执行完后，密钥会保存在默认路径：

• Mac/Linux：~/.ssh/id_ed25519.pub（如果用rsa算法就是id_rsa.pub）；

• Windows：C:\Users\你的用户名\.ssh\id_ed25519.pub（找不到的话，打开“此电脑”，地址栏输入%USERPROFILE%.ssh即可）。

3.3 第三步：复制SSH密钥到GitHub

需要把本地的公钥（.pub结尾的文件）内容复制到GitHub，步骤如下：

1. 打开公钥文件：
   Mac：终端输入cat ~/.ssh/id_ed25519.pub，会直接显示公钥内容；

2. Windows：用记事本打开C:\Users\你的用户名.ssh\id_ed25519.pub；

3. Linux：终端输入cat ~/.ssh/id_ed25519.pub。

4. 复制内容：从“ssh-ed25519”开头到邮箱结尾，完整复制，不要漏字符也不要多空格；

5. GitHub添加：登录GitHub→点击右上角头像→Settings→左侧SSH and GPG keys→New SSH key；

6. 填写信息：Title随便填（如“MacbookPro”“Windows10”），Key栏粘贴刚才复制的公钥，点击“Add SSH key”。

3.4 第四步：测试SSH连接是否成功

这一步必须做，验证连接是否通畅，避免后面部署踩坑。终端输入：

ssh -T git@github.com

第一次执行会提示“Are you sure you want to continue connecting (yes/no)?”，输入yes回车。

成功提示：Hi 你的用户名! You’ve successfully authenticated, but GitHub does not provide shell access. （看到这个就说明连接成功了）

新手易错点4：测试连接提示“Permission denied (publickey)”

解决办法：1. 检查公钥是否完整复制，有没有漏字符；2. 确认GitHub添加的是公钥（.pub结尾）不是私钥；3. 重新生成密钥（删除.ssh目录下的文件，重新执行ssh-keygen命令），再重新添加到GitHub。

四、Hexo安装与初始化（全平台通用）

环境和Git都配置好了，现在开始装Hexo并初始化博客。

4.1 全局安装Hexo-cli（命令行工具）

终端输入以下命令，Mac/Linux需要加sudo获取权限（Windows用管理员身份打开CMD/PowerShell，不用加sudo）：

# Mac/Linux
sudo npm install -g hexo-cli

# Windows（管理员CMD）
npm install -g hexo-cli

安装完成后，输入hexo -v，显示Hexo版本号（如hexo-cli: 4.3.0）即为成功。

新手易错点5：安装时提示“npm ERR! permission denied”

解决办法：Mac/Linux没加sudo；Windows没以管理员身份运行终端，右键CMD→“以管理员身份运行”再重新安装。

4.2 初始化Hexo博客目录

先选一个存放博客的目录（如Mac的Documents，Windows的桌面），终端切换到该目录（用cd命令，比如Windows输入cd C:\Users\你的用户名\Desktop），然后执行以下命令：

# 创建博客目录（blog是目录名，可自定义）
hexo init blog

# 进入博客目录
cd blog

# 安装依赖包
npm install

执行完成后，blog目录下会生成这些核心文件：

• _config.yml：全局配置文件（重要，后面要改）；

• source：存放文章（_posts目录）和静态资源；

• themes：主题目录；

• public：生成的静态页面（部署时同步到GitHub）。

新手易错点6：hexo init提示“git clone failed”

解决办法：网络问题导致无法克隆Hexo默认主题。可以换国内镜像，先执行npm config set registry https://registry.npm.taobao.org，再重新执行hexo init；如果还是不行，手动下载主题放到themes目录（具体可搜“Hexo 主题 手动安装”）。

4.3 本地预览Hexo博客

初始化完成后，在blog目录下执行以下命令，启动本地服务器：

hexo clean  # 清理缓存（首次可省略，后续修改配置后建议执行）
hexo g      # 生成静态页面（g是generate的缩写）
hexo s      # 启动本地服务器（s是server的缩写）

执行成功后，终端会提示“Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.”，打开浏览器输入http://localhost:4000，就能看到Hexo的默认博客页面了！

新手易错点7：hexo s提示“Port 4000 is already in use”

解决办法：4000端口被其他程序占用了。换个端口启动，命令改成hexo s -p 5000，然后浏览器访问http://localhost:5000即可。

五、配置Hexo并部署到GitHub Pages

本地预览没问题后，就可以部署到GitHub了，让别人也能访问你的博客。

5.1 第一步：在GitHub创建仓库（关键命名规则）

登录GitHub，点击右上角“+”→New repository，填写信息：

• Repository name：必须是“用户名.github.io”（比如我用户名是zhangsan，仓库名就是zhangsan.github.io），这是GitHub Pages的固定命名规则，错了无法访问；

• Description：随便填（如“My Hexo Blog”）；

• Visibility：选Public（私有仓库需要付费才能用Pages）；

• 勾选“Add a README file”；

• 点击“Create repository”。

新手易错点8：仓库名命名错误

解决办法：如果已经创建错了，在仓库页面→Settings→Repository name，修改成“用户名.github.io”，保存即可。

5.2 第二步：修改Hexo配置文件（_config.yml）

进入博客目录（cd blog），找到_config.yml文件（Mac用VS Code打开，Windows用记事本或VS Code打开），拉到最下面，找到“deploy”部分，修改成以下内容：

deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main  # 注意：GitHub新建仓库默认分支是main，老仓库可能是master，根据实际情况改

新手易错点9：配置文件缩进错误

解决办法：YAML配置文件对缩进要求严格，必须用空格缩进，不能用Tab。deploy下面的type、repo、branch前面要空2个空格，冒号后面要空1个空格。缩进错了会导致部署失败。

新手易错点10：repo地址填错

解决办法：repo地址要填SSH地址，不是HTTPS地址。在GitHub仓库页面→点击“Code”→选择“SSH”，复制地址即可（格式是git@github.com:用户名/仓库名.git）。

5.3 第三步：安装hexo-deployer-git插件

Hexo需要通过这个插件实现部署到Git，终端输入（在blog目录下执行）：

npm install hexo-deployer-git --save

安装完成后，没有报错就是成功了。

5.4 第四步：执行部署命令

在blog目录下执行以下命令（部署前建议先清理缓存）：

hexo clean
hexo g
hexo d  # d是deploy的缩写，部署命令

第一次执行hexo d可能会提示“Are you sure you want to continue connecting (yes/no)?”，输入yes回车即可。执行完成后，终端显示“Deploy done: git”就是部署成功了。

5.5 第五步：访问你的博客

部署完成后，等待1-2分钟（GitHub需要同步），打开浏览器输入“你的用户名.github.io”（比如zhangsan.github.io），就能看到你的Hexo博客了！

新手易错点11：访问是404页面

解决办法：1. 检查仓库名是否正确（用户名.github.io）；2. 检查_config.yml的branch是否和GitHub仓库的默认分支一致（现在默认是main，老仓库是master）；3. 重新执行hexo clean && hexo g && hexo d部署一次；4. 查看GitHub仓库的Pages配置：仓库→Settings→Pages→Source，确认分支是main，目录是/docs（如果没有docs目录，选/(root)），点击“Save”。

六、后续操作：写文章和换主题（新手必看）

6.1 写第一篇文章

终端在blog目录下执行：

hexo new "我的第一篇Hexo博客"

会在source/_posts目录下生成“我的第一篇Hexo博客.md”文件，用Markdown编辑器（如VS Code、Typora）打开，写完后执行hexo clean && hexo g && hexo d部署，就能在博客上看到了。

6.2 换主题（提升博客颜值）

Hexo默认主题比较朴素，推荐几个热门主题：Next（简洁）、Butterfly（美观，功能多）、Fluid（清新）。以Next为例，安装步骤：

# 在blog目录下执行
git clone https://github.com/next-theme/hexo-theme-next themes/next

然后修改_config.yml文件中的theme配置：

theme: next  # 把默认的landscape改成next

执行hexo clean && hexo g && hexo s，本地预览没问题后再部署即可。

七、总结：新手避坑核心要点

1. 环境选稳不选新：Node.js装LTS版，Git装官网最新版；

2. Git配置要闭环：用户信息→生成密钥→添加到GitHub→测试连接，一步都不能少；

3. 配置文件守规则：_config.yml用空格缩进，repo填SSH地址，branch和GitHub一致；

4. 部署前先测本地：hexo s预览没问题再部署，减少线上错误；

5. 遇到错误先看日志：终端报错信息是最好的排查线索，复制报错搜一下基本都有解决办法。

按照这个流程走，基本能避开90%的新手坑。如果还有问题，评论区留言，看到会回复～ 最后祝大家都能顺利搭起自己的Hexo博客！

——站长孙

后续拓展小提示

• 自定义域名：博客稳定运行后，可购买域名并在GitHub Pages和Hexo配置中设置，让博客更具辨识度；

• 插件推荐：想增强功能可尝试hexo-generator-sitemap（生成站点地图）、hexo-prism-plugin（代码高亮）等插件；

• 数据备份：建议定期备份博客目录下的source、themes文件夹和_config.yml文件，避免数据丢失。

（注：文档部分内容可能由 AI 生成）