Hexo 博客全攻略：从零开始搭建你的个人技术博客

新手友好指南 + 进阶技巧 + 常见问题解决

📌 欢迎来到 Hexo 的世界！

欢迎使用 Hexo —— 一个快速、简洁且功能强大的博客框架！
这是你的第一篇博客，也是你迈向技术写作的第一步。Hexo 支持 Markdown 格式，只需简单编写，即可生成美观的静态网站。

🎯 Hexo 的核心优势

  • 闪电般生成速度：千篇文档秒级生成
  • 高度可定制：超 200+ 主题和插件生态
  • 多平台部署：GitHub Pages、Netlify、Vercel 等一键发布
  • 跨平台支持：Windows/macOS/Linux 全兼容

如需深入学习，请参考官方文档：
📚 Hexo 官方文档 | 🛠️ 故障排查指南

🚀 快速入门指南

1️⃣ 创建你的第一篇博客

1
$ hexo new "我的第一篇博客"

此命令会生成一个 .md 文件，位于 source/_posts/ 目录下。
进阶技巧：

  • 使用 hexo new draft "草稿标题" 创建草稿（保存在 _drafts 目录）
  • 草稿完成后通过 hexo publish "草稿标题" 发布
  • 支持自定义模板：hexo new [layout] <title>（默认 layout 为 post）

2️⃣ 启动本地开发服务器

1
$ hexo server

访问 http://localhost:4000 查看效果。
实用参数：

  • 更改端口：hexo server -p 5000
  • 静态模式（生产环境）：hexo server -s
  • 自定义 IP：hexo server -i 192.168.1.1

3️⃣ 生成静态文件

1
$ hexo generate

生成的文件会自动放入 public/ 文件夹。
自动化建议：

  • 监控文件变化：hexo generate --watch（修改后自动重新生成）
  • 清理缓存：hexo clean（解决数据未更新问题）

4️⃣ 一键部署到互联网

1
$ hexo deploy

部署配置示例（GitHub Pages）：
在 _config.yml 中添加：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/yourname/yourname.github.io.git
  branch: main

支持平台：

  • GitHub/Gitee Pages
  • Netlify/Vercel
  • FTP/SFTP
  • Heroku
    完整部署方式请查看 部署指南

🛠️ 进阶操作手册

🎨 主题定制指南

  1. 安装主题（以 NexT 为例） 
    1
    git clone https://github.com/theme-next/hexo-theme-next themes/next
  2. 启用主题：修改 _config.yml 
    1
    theme: next
  3. 深度定制：编辑 themes/next/_config.yml
    • 修改配色方案
    • 开启评论系统（Valine/Gitalk）
    • 添加 SEO 优化配置

🔌 插件生态扩展功能

推荐插件：

  • 代码高亮：hexo-prism-plugin
  • 自动摘要生成：hexo-autodescription
  • 生成站点地图：hexo-generator-sitemap
  • RSS 订阅支持：hexo-generator-feed

安装示例： 

1
npm install hexo-prism-plugin --save

在 _config.yml 中启用：

1
2
3
prism_plugin:
  enable: true
  preprocess: true

💡 高效写作技巧

  1. Markdown 语法速查：

    • 标题：# 一级标题 到 ###### 六级标题
    • 列表： 
      1
      2
      3
      - 项目1  
      - 项目2  
        - 子项目2.1
    • 代码块： 
      1
      2
      ```javascript
      console.log("Hello World");
      1
      2
      3
      4

      2. **插入图片**：  
         ```markdown
         ![替代文本](/images/your-image.jpg)

  2. 跨文章链接： 

    1
    [点击这里](/posts/your-post-title)

🧰 常见问题解决方案

❗ YAML 解析错误

错误示例： 

1
tags:technology,linux

修正写法： 

1
tags: [technology, linux]

或：

1
2
3
tags:
  - technology
  - linux

🚫 端口占用问题

1
Error: listen EADDRINUSE

解决方法： 

1
hexo server -p 5000  # 更换端口

🧹 内存不足问题

1
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed

解决方法：
修改 hexo 可执行文件的内存限制（位于 node_modules/.bin/hexo）： 

1
#!/usr/bin/env node --max_old_space_size=8192

📚 深度学习资源推荐

  1. 官方文档：Hexo Docs
  2. 主题市场：Hexo Themes
  3. 插件市场：Hexo Plugins
  4. 中文社区：Hexo 中文论坛

🧪 实战案例分享

场景：从零搭建 GitHub Pages 博客

  1. 安装 Hexo： 
    1
    2
    3
    npm install -g hexo-cli
    hexo init my-blog
    cd my-blog && npm install
  2. 配置部署信息： 
    1
    2
    3
    4
    _config.yml:
    deploy:
      type: git
      repo: https://github.com/yourname/yourname.github.io
  3. 生成并部署： 
    1
    hexo generate && hexo deploy
  4. 访问：https://yourname.github.io

📝 小结：Hexo 使用路线图

阶段 推荐操作
第1天 初始化博客、写第一篇文章、本地预览
第3天 更换主题、添加插件、配置部署
第1周 优化 SEO、添加评论系统、设置自定义域名
第1月 编写自动化脚本、搭建 CI/CD 流程

通过这篇指南，你已掌握 Hexo 的核心操作与进阶技巧。现在，是时候开始你的写作之旅了！如果遇到任何问题，欢迎在 GitHub Issues 提问，社区将为你提供支持。