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，显示版本号则成功。二、安装并初始化 Hexo1. 全局安装 Hexo CLI终端执行：
npm install -g hexo-cli
验证：hexo -v 显示版本号则成功。
2. 初始化博客项目
mkdir my-hexo-blog # 新建博客文件夹
cd my-hexo-blog # 进入文件夹
hexo init # 初始化 Hexo
npm install # 安装依赖
三、本地预览与第一篇文章1. 启动本地服务器
hexo clean && hexo g && hexo s
访问 http://localhost:4000 即可预览。2. 发布第一篇文章
hexo new "我的第一篇 Hexo 博客"
打开 source/_posts/我的第一篇 Hexo 博客.md，用 Markdown 写内容后，重新执行 hexo clean && hexo g && hexo s 即可看到文章。四、更换主题（以 Butterfly 为例）1. 下载主题
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
2. 安装主题依赖
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. 安装部署插件
npm install hexo-deployer-git --save
3. 配置部署信息（修改根目录 _config.yml）
deploy:
type: git
repo: https://github.com/你的用户名/你的用户名.github.io.git
branch: main
4. 执行部署
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 博客，遇到问题可参考「踩坑指南」快速解决～