Hexo · 快速上手

面向新手的 Hexo 操作说明。只保留最有用的命令与范例，能直接复制粘贴跑起来。

1) 新建文章

# 新建一篇普通文章（建议文件名用英文，便于链接与版本管理）
hexo new "hello-hexo-quickstart"

# 也可指定类型：post（默认）/ draft / page
hexo new post  "my-first-post"
hexo new draft "post-draft"        # 草稿（不会被发布）
hexo publish draft "post-draft"    # 草稿转正式文章
hexo new page "about"              # 生成独立页面：/about/

2) 本地预览

# 启动本地服务（默认 http://localhost:4000）
hexo s

# 可选：自动打开浏览器、指定端口
hexo s -o -p 4001

退出预览：在终端按 Ctrl + C。

3) 写作：Front-matter（安全模板）

避免 YAML 报错的最小模板——列表一律用 -，不要多余缩进或反斜杠：

---
title: Your Post Title
date: {{ date }}
updated: {{ date }}
categories:
  - 教程
tags:
  - Hexo
description: 一句话描述本文内容。
comments: true
toc: true
toc_number: true
aside: true
background: "#ffffff"
---

常见字段说明：

• categories / tags：都是列表（用 -）。
• description：摘要文本，很多主题会用于 SEO/预览卡片。
• 主题自带的 cover / top_img 可按需添加；不需要时直接删掉字段，不要留空值。

4) 生成静态文件

# 可选：先清理，避免旧缓存导致显示异常
hexo clean

# 生成到 public/ 目录
hexo generate
# 简写
hexo g

5) 部署到远程（以 GitHub Pages 为例）

5.1 安装部署插件（首次）

npm i hexo-deployer-git -D

5.2 配置 _config.yml

deploy:
  type: git
  repo: https://github.com/<your-username>/<your-username>.github.io.git
  branch: main   # 或者 gh-pages，取决于你的仓库设置

5.3 一键生成并部署

hexo g -d
# 或分步：hexo g && hexo d

若仓库开启了自定义域名（CNAME），请确保仓库根目录有正确的 CNAME 文件。

6) 命令速查表

目的	命令
新建文章	hexo new "My Post"
新建草稿	hexo new draft "My Draft"
草稿转正式	hexo publish draft "My Draft"
本地预览	hexo s / hexo s -o -p 4001
清理缓存	hexo clean
生成静态文件	hexo g
部署	hexo d / hexo g -d

7) 常见问题（快速排查）

• YAMLException（前言区解析错误）
  多半是列表写成了 * 项目 或缩进错位；用上面的“安全模板”重写前言区。
• 图片不显示
  确认图片位于 source/img/，引用用绝对路径：/img/xxx.png。
• 部署报错：Deployer not found: git
  还没装 hexo-deployer-git：执行 npm i hexo-deployer-git -D。
• 改了不生效
  执行 hexo clean && hexo s，或清除浏览器缓存/强刷。
• GitHub Pages 没有更新
  检查仓库 Actions/Pages 状态、分支是否正确、public/ 是否包含最新生成内容。

8) 写作小贴士

• 文件名与链接：文件名用英文、短横线分词，比如 lua-xlua-syntax-tutorial.md。
• 代码高亮：代码块使用三反引号并指定语言，如 bash</code> / <code>js。
• 长文章导航：开启 toc: true 与 toc_number: true，目录更清晰。
• 更新日期：不想维护 updated 时可以删掉该字段，避免重复改动。

---