Hexo 命令完全手册：从入门到精通的命令行指南
**
Hexo 作为一款高效的静态博客框架，其所有核心操作都可以通过命令行完成。本文将系统梳理 Hexo 从安装、初始化到部署的全流程命令，涵盖基础操作、内容管理、配置优化、插件使用等场景，帮助你快速掌握 Hexo 命令行工具的使用技巧，提升博客搭建与维护效率。
一、环境准备与 Hexo 安装
在使用 Hexo 命令前，需先完成环境配置与框架安装。Hexo 基于 Node.js 运行，因此必须先安装 Node.js（建议版本 ≥ 14.0.0）和 Git。
1.1 检查依赖环境
安装前先验证 Node.js 和 Git 是否已正确安装：
# 检查 Node.js 版本（需 ≥ 14.0.0）
node -v 或 node --version
# 检查 npm 版本（Node.js 自带，用于包管理）
npm -v 或 npm --version
# 检查 Git 版本
git -v 或 git --version
1.2 全局安装 Hexo CLI
通过 npm 全局安装 Hexo 命令行工具（Hexo CLI），安装后可在任意目录使用 hexo 命令：
# 全局安装 Hexo
npm install -g hexo-cli
# 验证 Hexo 是否安装成功（查看版本）
hexo -v 或 hexo --version
注意：若出现权限问题（如 macOS/Linux 下的 EACCES 错误），可避免使用 sudo，而是通过 nvm 管理 Node.js 版本，或修改 npm 全局包安装路径。
二、基础命令：初始化与项目管理
初始化 Hexo 项目后，所有操作需在项目根目录下执行。以下是项目创建、启动、清理等核心基础命令。
2.1 初始化 Hexo 项目
在指定目录创建新的 Hexo 项目（blog 为项目名，可自定义）：
# 1. 进入目标目录（示例：进入用户目录下的 "projects" 文件夹）
cd ~/projects
# 2. 初始化 Hexo 项目（会创建名为 "blog" 的文件夹，包含所有配置和文件）
hexo init blog
# 3. 进入项目根目录（后续所有命令需在此目录执行）
cd blog
# 4. 安装项目依赖（初始化后自动生成 package.json，需安装依赖才能运行）
npm install
2.2 本地预览：启动开发服务器
启动本地服务器，实时预览博客效果（默认支持热重载，修改文件后无需重启服务器）：
# 基础命令：启动本地服务器，默认端口 4000
hexo server 或 hexo s
# 常用参数：
# 1. 自定义端口（如端口 5000）
hexo s -p 5000 或 hexo s --port 5000
# 2. 启动后自动打开浏览器（需浏览器支持）
hexo s -o 或 hexo s --open
# 3. 关闭热重载（仅在调试时使用）
hexo s -n 或 hexo s --no-incremental
启动后访问 http://localhost:4000 即可查看本地博客。
2.3 生成静态文件
Hexo 会将 Markdown 文章、主题模板等编译为 HTML/CSS/JS 等静态文件，生成的文件默认存放在 public 目录：
# 基础命令：生成静态文件
hexo generate 或 hexo g
# 常用参数：
# 1. 强制重新生成所有文件（忽略缓存，解决文件更新不生效问题）
hexo g -f 或 hexo g --force
# 2. 生成后显示文件大小统计
hexo g -s 或 hexo g --size
2.4 清理生成文件与缓存
当修改主题、配置或遇到文件冲突时，需清理 public 目录（生成的静态文件）和 db.json（缓存文件）：
# 清理 public 目录和缓存
hexo clean
建议在执行 hexo g 前先运行 hexo clean，避免旧文件干扰。
三、内容管理：文章、页面与分类
Hexo 的核心功能是管理博客内容，包括创建文章、页面、分类、标签等，以下是常用内容管理命令。
3.1 创建新文章
创建 Markdown 格式的文章，默认存放在 source/_posts 目录：
# 基础命令：创建标题为 "Hello Hexo" 的文章（文件名自动转为小写，空格替换为 "-"）
hexo new "Hello Hexo" 或 hexo n "Hello Hexo"
# 常用参数与扩展：
# 1. 指定文章模板（需先在 scaffolds 目录自定义模板，如 "draft" 草稿模板）
hexo n draft "未发布的草稿"
# 2. 创建带分类和标签的文章（命令行直接指定，无需手动编辑 Front-matter）
hexo n "Hexo 命令手册" --category "技术文档" --tags "Hexo,命令行"
# 3. 创建文章时指定日期（格式：YYYY-MM-DD，如 2024-05-20）
hexo n "指定日期的文章" --date 2024-05-20
文章生成后，会自动在 Markdown 文件头部添加 Front-matter（如标题、日期、分类、标签等），可手动编辑修改。
3.2 草稿管理
Hexo 支持草稿功能，未发布的文章可先存为草稿（默认存放在 source/_drafts 目录，不参与静态文件生成）：
# 1. 创建草稿（使用 draft 模板）
hexo n draft "我的草稿"
# 2. 预览草稿（本地服务器需添加 --draft 参数才能显示草稿）
hexo s --draft
# 3. 发布草稿（将草稿移至 source/_posts 目录，转为正式文章）
hexo publish draft "我的草稿" 或 hexo p draft "我的草稿"
3.3 创建独立页面
创建独立页面（如 “关于我”“分类页”“标签页”），默认存放在 source 目录下的对应文件夹中：
# 基础命令：创建 "关于我" 页面（生成 source/about/index.md）
hexo new page "about" 或 hexo n page "about"
# 常用场景：
# 1. 创建分类页（需主题支持，生成 source/categories/index.md）
hexo n page "categories"
# 2. 创建标签页（需主题支持，生成 source/tags/index.md）
hexo n page "tags"
# 3. 创建带自定义路径的页面（如 source/tech/hexo/index.md）
hexo n page "tech/hexo"
3.4 内容统计与列表
查看博客中的文章、页面、分类、标签等统计信息：
# 查看所有文章列表（含标题、日期、路径）
hexo list posts
# 查看所有页面列表
hexo list pages
# 查看所有分类及对应文章数
hexo list categories
# 查看所有标签及对应文章数
hexo list tags
四、配置与优化：自定义博客行为
Hexo 的配置文件为 _config.yml（项目根目录），可通过命令行或手动编辑修改配置。以下是常用配置相关命令。
4.1 查看配置信息
快速查看 Hexo 核心配置（如站点标题、主题、时区等）：
# 查看所有配置（输出完整的 _config.yml 内容）
cat _config.yml
# 查看指定配置（如查看当前使用的主题）
grep "theme" _config.yml # Linux/macOS
findstr "theme" _config.yml # Windows
4.2 插件安装与管理
Hexo 生态丰富，可通过 npm 安装插件扩展功能（如评论、搜索、SEO 优化等）：
# 1. 安装插件（示例：安装 hexo-generator-sitemap 生成站点地图）
npm install hexo-generator-sitemap --save
# 2. 卸载插件（示例：卸载 hexo-generator-sitemap）
npm uninstall hexo-generator-sitemap --save
# 3. 更新插件（更新所有项目依赖，包括 Hexo 插件）
npm update
# 4. 查看已安装的插件（查看 package.json 中的 dependencies）
cat package.json | grep "hexo-" # Linux/macOS
findstr "hexo-" package.json # Windows
安装插件后，需在 _config.yml 中配置插件参数（具体配置参考插件文档）。
4.3 主题管理
Hexo 主题存放在 themes 目录，可通过 Git 克隆或手动下载主题：
# 1. 克隆主题（示例：克隆 Next 主题，目前主流主题之一）
git clone https://github.com/next-theme/hexo-theme-next.git themes/next
# 2. 切换主题（修改 _config.yml 中的 theme 字段，如 theme: next）
# 手动编辑 _config.yml 或使用命令行替换（Linux/macOS）：
sed -i '' 's/theme: .*/theme: next/' _config.yml
# 3. 更新主题（进入主题目录，拉取最新代码）
cd themes/next
git pull
cd ../.. # 返回项目根目录
五、部署命令：将博客发布到服务器
生成静态文件后，需将 public 目录部署到服务器（如 GitHub Pages、GitLab Pages、Vercel、Netlify 等）。Hexo 提供 hexo deploy 命令简化部署流程，需先在 _config.yml 中配置部署信息。
5.1 配置部署信息
在 _config.yml 末尾添加部署配置（以 GitHub Pages 为例）：
deploy:
type: git
repo: https://github.com/your-username/your-username.github.io.git # 你的 GitHub 仓库地址
branch: main # 部署分支（GitHub Pages 通常为 main 或 gh-pages）
若使用其他平台（如 Vercel），需安装对应插件（如 hexo-deployer-vercel）并配置 type: vercel。
5.2 执行部署
部署前需先安装 hexo-deployer-git 插件（Git 部署必备）：
# 安装 Git 部署插件
npm install hexo-deployer-git --save
# 执行部署（自动生成静态文件并推送至配置的仓库）
hexo deploy 或 hexo d
# 常用参数：
# 1. 部署前强制重新生成静态文件（等价于 hexo clean && hexo g && hexo d）
hexo d -g 或 hexo d --generate
# 2. 显示部署过程的详细日志
hexo d --debug
快捷命令：若需频繁执行 “清理 - 生成 - 部署” 流程，可在 package.json 中添加脚本：
"scripts": {
"deploy": "hexo clean && hexo g && hexo d"
}
之后只需执行 npm run deploy 即可完成全流程。
六、高级命令与实用技巧
6.1 自定义命令（通过 Hexo 插件）
Hexo 支持通过插件扩展命令，例如安装 hexo-cli-plugin 自定义脚本，或在 scripts 目录下创建 .js 文件编写自定义逻辑（如自动添加文章模板、批量修改 Front-matter 等）。
示例：在 scripts/auto-tag.js 中添加自动为文章添加标签的逻辑：
hexo.extend.filter.register('before_post_render', (data) => {
// 若文章无标签，自动添加 "Hexo" 标签
if (!data.tags || data.tags.length === 0) {
data.tags = ['Hexo'];
}
return data;
});
6.2 调试命令
当遇到命令执行错误或博客异常时，可通过调试模式查看详细日志：
# 启动调试模式（任何命令均可添加 --debug 参数）
hexo s --debug # 调试本地服务器
hexo g --debug # 调试生成过程
hexo d --debug # 调试部署过程
调试日志会显示详细的错误信息、文件路径、插件加载情况，便于定位问题。
6.3 命令别名与快捷操作
为常用命令设置别名（以 Bash 为例，编辑 ~/.bashrc 或 ~/.zshrc）：
# Hexo 命令别名
alias hc="hexo clean"
alias hg="hexo g"
alias hs="hexo s"
alias hd="hexo d"
alias hgd="hexo clean && hexo g && hexo d" # 一键部署
添加后执行 source ~/.bashrc（或 source ~/.zshrc）生效，之后只需输入 hgd 即可完成 “清理 - 生成 - 部署”。
七、常见问题与解决方案
- 执行 hexo 命令提示 “command not found”
原因：Hexo 未全局安装或 Node.js 环境变量配置错误。
解决：重新执行 npm install -g hexo-cli，并检查 Node.js 的 bin 目录是否在系统环境变量 PATH 中。
- 本地预览时文章不显示
原因：文章存放在 _drafts 目录（草稿），或 Front-matter 中 published: false。
解决：执行 hexo publish draft “文章名” 发布草稿，或修改 published: true。
- 部署后 GitHub Pages 显示 404
原因：部署分支错误（如 GitHub Pages 需 main 或 gh-pages 分支），或 public 目录未正确推送。
解决：检查 _config.yml 中 deploy.branch 配置，并重执行 hexo d -g。
总结
Hexo 命令行工具是博客开发与维护的核心，掌握本文梳理的命令可覆盖从环境搭建到部署的全流程需求。建议根据实际使用场景，将常用命令（如一键部署、本地预览）设置别名，结合插件扩展功能，进一步提升效率。若需深入了解某一命令或插件，可参考 Hexo 官方文档 或对应的插件说明。