hexo

简明 Hexo 使用教程

这是一个面向初学者的快速入门指南，包含安装、常用命令、调试与部署要点。

1. 前提

• Node.js：建议使用 LTS 版本（可从 https://nodejs.org 下载）。
• Git：用于部署到 GitHub Pages 或拉取主题。

2. 安装 Hexo（全局）

在终端中运行：

npm install -g hexo-cli

如果你更喜欢局部安装，也可以在项目内使用 npx hexo。

3. 新建博客或初始化已有目录

• 新建一个新的 Hexo 项目（示例）：

hexo init my-blog
cd my-blog
npm install

• 如果你已经有现成仓库，进入仓库目录运行 npm install 即可。

4. 创建文章

• 新建一篇文章：

hexo new "我的第一篇文章"

• 新建页面：

hexo new page "about"

创建后会在 source/_posts/ 下生成对应的 Markdown 文件，编辑该文件撰写内容。

5. 常用命令（本地预览与生成）

• 生成静态文件：

hexo generate  # 或 hexo g

• 启动本地服务器并自动生成：

hexo server    # 或 hexo s

然后打开 http://localhost:4000 查看效果。

• 清理缓存与旧文件（遇到生成问题时有用）：

hexo clean

6. 部署（示例：GitHub Pages）

1. 在 _config.yml 中配置 deploy 部分（或使用 hexo-deployer-git）：

deploy:
	type: git
	repo: https://github.com/<用户名>/<仓库名>.git
	branch: gh-pages

2. 安装 deploy 插件并部署：

npm install hexo-deployer-git --save
hexo generate
hexo deploy  # 或 hexo d

更多部署方式：FTP、Netlify、Vercel 等，按照各平台说明配置。

7. 主题与插件

• 下载并切换主题：将主题放在 themes/ 目录并在 _config.yml 中设置 theme: 主题名。
• 安装插件：使用 npm install <包名> --save 并在 Hexo 或主题文档中按需配置。

8. 常见问题与排查

• 页面生成为空：先运行 hexo clean，然后 hexo g，查看终端报错。
• 主题样式缺失：确认已安装主题依赖并执行 npm install；检查主题的 source、_config.yml 配置。
• 部署不上去：确认 repo 地址与 branch 配置正确，并具有推送权限。

9. 进阶建议

• 使用 Git 管理源码，部署只放静态文件到 gh-pages 分支。
• 在本地添加 CI（GitHub Actions）自动化 hexo generate + hexo deploy。

10. 参考资源

• 官方文档：https://hexo.io
• 中文指南与社区主题：搜索主题仓库（例如 Hexo 主题 Next）

---