Hexo 个人博客从搭建到上线全流程（含踩坑指南）
一、环境准备（必做）
1. 安装 Node.js
作用：Hexo 运行的底层环境
下载地址：Node.js 官网（选 LTS 长期支持版，如 v20.x）
验证：终端执行 node -v 和 npm -v，显示版本号则成功。
2. 安装 Git
作用：版本控制 + 部署到 GitHub 必备
下载地址：Git 官网（Windows 需勾选「Add Git to PATH」）
验证：终端执行 git --version，显示版本号则成功。
二、安装并初始化 Hexo
1. 全局安装 Hexo CLI
终端执行：
bash
复制代码
npm install -g hexo-cli
验证：hexo -v 显示版本号则成功。
2. 初始化博客项目
bash
复制代码
mkdir my-hexo-blog # 新建博客文件夹
cd my-hexo-blog # 进入文件夹
hexo init # 初始化 Hexo
npm install # 安装依赖
三、本地预览与第一篇文章
1. 启动本地服务器
bash
复制代码
hexo clean && hexo g && hexo s
访问 http://localhost:4000 即可预览。
2. 发布第一篇文章
bash
复制代码
hexo new "我的第一篇 Hexo 博客"
打开 source/_posts/我的第一篇 Hexo 博客.md，用 Markdown 写内容后，重新执行 hexo clean && hexo g && hexo s 即可看到文章。
四、更换主题（以 Butterfly 为例）
1. 下载主题
bash
复制代码
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
2. 安装主题依赖
bash
复制代码
npm install hexo-renderer-pug hexo-renderer-stylus --save
3. 配置主题
复制 themes/butterfly/_config.yml 到根目录，并重命名为 _config.butterfly.yml。
修改根目录 _config.yml，设置 theme: butterfly。
五、部署到 GitHub Pages（免费上线）
1. 准备 GitHub 仓库
新建仓库，名称必须为 你的用户名.github.io（如 xxx.github.io）。
2. 安装部署插件
bash
复制代码
npm install hexo-deployer-git --save
3. 配置部署信息（修改根目录 _config.yml）
yaml
复制代码
deploy:
type: git
repo: https://github.com/你的用户名/你的用户名.github.io.git
branch: main
4. 执行部署
bash
复制代码
hexo clean && hexo g && hexo d
访问 https://你的用户名.github.io 即可看到线上博客。
六、踩坑指南（避坑必备）
1. 「没有权限修改 _config.yml 文件」
原因：文件权限不足或被占用。
解决 ：
Windows：右键编辑器 →「以管理员身份运行」，或修改文件夹权限（属性→安全→完全控制）。
Mac/Linux：终端执行 sudo chown -R $USER 博客文件夹 赋予权限。
2. 部署时「Spawn failed」错误
原因：Git 环境变量未配置、部署配置错误、网络问题等。
解决 ：
检查 Git 环境变量（终端执行 git --version 验证）。
核对 _config.yml 中 deploy 的 repo 和 branch 是否正确。
国内网络可尝试挂梯子，或修改 Git 镜像：git config --global url."https://github.com.cnpmjs.org/".insteadOf "https://github.com/"。
3. GitHub 密码验证失败
原因：GitHub 已停用 HTTPS 密码验证，需用个人访问令牌或 SSH。
解决 ：
生成 GitHub 个人访问令牌，部署时密码填令牌。
配置 SSH 免密：生成 SSH 密钥 → 配置到 GitHub → 修改 deploy 的 repo 为 SSH 地址（git@github.com:xxx/xxx.github.io.git）。
4. SSH 连接「Connection refused」
原因：端口 22 被屏蔽。
解决 ：修改 SSH 配置走 443 端口，在 ~/.ssh/config 中添加：
复制代码
Host github.com
Hostname ssh.github.com
Port 443
5. YAML 配置「duplicated mapping key」错误
原因 ：配置文件中出现重复键名（如 waline: 重复）。
解决 ：打开 _config.butterfly.yml，删除重复的键块，确保同一层级键名唯一。
七、优化与扩展
自定义域名 ：在 GitHub Pages 配置中绑定域名，并在 source/ 下新建 CNAME 文件填写域名。
评论功能 ：推荐用 Waline，需先部署服务端获取 serverURL，再在主题配置中启用。
SEO 优化 ：安装 hexo-generator-sitemap 等插件，配置站点关键词和描述。
按照以上步骤，即可从 0 到 1 搭建并个性化你的 Hexo 博客，遇到问题可参考「踩坑指南」快速解决～