从零开始搭建 Hexo 博客（四）：一键部署脚本与常见错误排查

上一篇已完成博客部署，但每次输入 hexo clean && hexo g && hexo d 过于繁琐。本篇将实现一键部署，并解决 90% 的 Hexo 部署常见问题，精简实操步骤，避免冗余。

一、创建一键部署脚本（实操精简版）

1. 新建脚本文件

在博客根目录（如 D:\Blog\my-blog）新建 deploy.sh 文件（建议用 VS Code 创建，确保编码为 UTF-8）。

2. 脚本内容（直接复制）


#!/bin/bash

echo "🚀 开始部署流程..."

hexo clean && echo "🧹 缓存清理完成"

hexo generate && echo "📄 静态文件生成完成"

hexo deploy && echo "✅ 部署成功！请等待 1-3 分钟访问：https://hyrx-tg.github.io"

3. 执行脚本（关键步骤）

💡 Windows 用户注意：

右键 deploy.sh → Git Bash Here，先赋予执行权限，再运行脚本：


chmod +x deploy.sh  # 赋予执行权限（仅首次需要）

./deploy.sh        # 执行一键部署

⚠️ 注意：密码框需粘贴 GitHub Token，不可输入 GitHub 密码，否则会认证失败。

二、五大常见错误 & 解决方案（精准避坑）

| 错误现象 | 核心原因 | 解决方案 |

| :— | :— | :— |

| 页面空白（白屏） | JS/CSS 被 Git CRLF 转换破坏 | 1. 根目录添加 .gitattributes 文件；2. 重新执行一键部署 |

| 文章无法滚动 | 代码块未用 包裹 | 所有代码块统一用bash（或对应语言）包裹，结尾闭合 |

| 404 页面不存在 | 仓库名错误或分支非 main | 1. 确认仓库名为「用户名.github.io」；2. 检查 _config.yml 中 branch: main |

| 部署认证失败 | 误用 GitHub 密码 | 密码框粘贴 GitHub Token（参考第三篇 Token 生成步骤） |

| 本地预览正常，线上空白 | 资源路径大小写敏感 | 所有资源路径统一用小写（如 /img/avatar.jpg） |

三、线上问题调试技巧（快速定位）

查看原始 HTML：访问 https://raw.githubusercontent.com/用户名/用户名.github.io/main/index.html，检查是否有 Hexo 生成的内容（排除部署未生效问题）；
浏览器调试：按 F12 打开 Console，查看 JS 报错（常见 404 资源缺失、CORS 跨域）；
本地验证：先执行 hexo server，访问 http://localhost:4000 确认无错后，再执行一键部署。

四、使用说明 & 总结

1. 脚本效果

无需重复输入长命令，仅用 ./deploy.sh 即可完成「清理-生成-部署」全流程，节省 80% 操作时间。

2. 部署注意事项

打开 my-final-blog 目录，删除原有第三、四篇文档；
新建对应文档，分别粘贴第三、四篇内容（确保格式正确）；
首次部署可执行 hexo clean && hexo generate && hexo deploy 验证，后续用一键脚本即可。

3. 核心避坑总结

| 问题 | 原因 | 解决方案 |

| :— | :— | :— |

| YAML 解析失败 | Front-matter 不完整 | 文档开头必须以 — 包裹，包含 title、date、tags 字段 |

| 代码块报错 | 代码块侵入 YAML 区域 | 确保 — 闭合后，再编写正文和代码块 |

| 部署失败 | 文件格式错误 | 严格遵循标准 Markdown + YAML 结构，避免乱码、格式错乱 |

⚠️ 补充：若访问 https://hyrx-tg.github.io 出现「网页解析失败」，大概率是部署未生效（等待 3 分钟后重试）或仓库名、分支配置错误，按上述 404 错误解决方案排查即可。

下一篇：写作规范与长期维护（高效写博客 + 长期避坑）。