hexo 学习►入门知识

hexo 学习 0016:hexo 命令

在 Hexo 的日常运维中，命令行指令是连接构思与成品的桥梁。从搭建环境到内容创作，再到部署上线，每一个环节都依赖于精准的指令操作。本文将围绕 Hexo 的核心指令集展开，详细讲解它们的功能、参数以及容易混淆的概念，确保你对常用命令了如指掌。

指令说明

Hexo 的指令体系涵盖了从初始化到调试的全流程，每一个动词都对应着特定的生命周期阶段。

init
该指令用于初始化一个新的网站项目。执行 hexo init 后，Hexo 会自动克隆官方的 starter 仓库和默认主题（Landscape）到当前目录，并使用 npm、Yarn 或 pnpm 自动安装依赖包。如果不指定文件夹名称，项目将直接在当前目录生成。这一步相当于完成了“下载脚手架 -> 安装依赖 -> 配置基础文件”的全过程。

new
用于创建新的文章、页面或草稿。这是内容创作的入口。如果你不指定文章的布局（layout），Hexo 会读取 _config.yml 中的 default_layout 参数作为默认值。特别地，你可以使用 draft 布局来创建草稿，这些草稿存放在 source/_drafts 目录下，不会被发布到线上。

generate
这是生成静态文件的核心指令。Hexo 作为一个静态博客生成器，正是通过这个命令将你的 Markdown 文件和主题模板转换为 HTML、CSS 和 JS 文件。生成的文件会存放在 public 目录下。在部署之前，通常都需要执行这一步。

server
用于在本地启动一个开发服务器。执行该命令后，你可以在浏览器中通过 http://localhost:4000/ 实时预览博客效果。这在调试主题或撰写文章时非常有用。你可以结合 --watch 参数，实现文件修改后自动刷新。

deploy
用于部署你的网站。执行该命令会将生成好的静态文件推送到你配置的远程仓库（如 GitHub Pages、GitCafe 等）。在执行部署前，通常需要先生成静态文件。

render
用于渲染指定的文件。如果你只想测试某一个 Markdown 文件或模板的渲染效果，可以使用这个命令，配合 --output 参数指定输出路径。

migrate
用于从其他博客系统（如 WordPress、Joomla 等）迁移内容。如果你之前使用其他平台，可以利用迁移插件将旧内容导入到 Hexo 的格式中。

clean
用于清理缓存和生成的文件。执行该命令会删除 public 目录下的所有静态文件以及根目录下的 db.json 缓存文件。当你发现页面显示异常或缓存未更新时，通常建议先执行 hexo clean 来清除旧文件，再重新生成。

list
用于列出网站的所有路由信息。你可以通过指定 type 参数来查看特定类型的路由，方便排查链接问题。

version
用于显示当前安装的 Hexo 版本信息。当你需要确认环境版本或向社区求助时，这个信息非常关键。

config
用于读取或修改网站的配置文件 _config.yml。如果只指定 key，则展示该键的值；如果同时指定 key 和 value，则会修改配置文件中对应的值。

全局参数与模式

除了特定指令，Hexo 还支持一些全局参数和运行模式，用于改变程序的运行环境。

安全模式 (--safe)
在安全模式下，Hexo 不会加载任何插件和脚本。当你安装了新插件导致博客无法启动，或者遇到难以排查的错误时，可以尝试以安全模式运行，以此判断问题是否由插件引起。

调试模式 (--debug)
在终端中显示详细的调试信息，并将日志记录到 debug.log 文件中。如果你发现了疑似 Bug，开启调试模式重新执行一次命令，可以查看具体的执行流程和报错细节，方便在 GitHub 上提交 Issue。

简洁模式 (--silent)
静默输出，终端中不会显示任何日志信息。适用于在自动化脚本中运行，避免日志刷屏。

自定义配置文件 (--config)
允许你指定一个或多个自定义配置文件，替代默认的 _config.yml。你可以指定单个文件，也可以用逗号分隔指定多个文件（无空格），Hexo 会按顺序合并它们。

显示草稿 (--draft)
强制显示 source/_drafts 文件夹中的草稿文章。通常用于在本地预览草稿效果。

自定义工作目录 (--cwd)
允许你指定当前工作目录（Current working directory）的路径。如果你的 Hexo 项目不在当前终端所在的目录，你可以使用这个参数来指定项目路径，而不需要切换终端目录。

概念辨析：常用指令与参数的区别

在使用 Hexo 指令时，有几个参数和指令容易混淆，理解它们的区别能让你的操作更精准。

  • hexo generate与hexo deploy的关系
    generate 是生成静态文件，deploy 是将文件上传到服务器。它们是两个独立的步骤。虽然 deploy 指令支持 -g 参数来在部署前自动 generate，但在实际开发中，建议先手动执行 hexo generate 查看是否有报错，确认无误后再执行 hexo deploy，以避免因生成失败导致部署中断。
  • --config与--cwd的作用范围
    --config 用于指定自定义的配置文件路径（如 custom.yml），它会覆盖默认的 _config.yml。而 --cwd 用于指定当前工作目录（Current working directory）。如果你的 Hexo 项目不在当前终端所在的目录，你可以使用 --cwd 来指定项目路径，而不需要切换终端目录。
  • --safe与--debug的使用场景
    --safe 是安全模式，它会禁用所有插件和脚本。当你安装了新插件导致博客无法启动时，可以用这个模式来排查是否是插件引起的问题。--debug 是调试模式，它会在终端输出详细的调试信息，并记录到 debug.log 文件中。当你遇到难以解决的 Bug 时，开启调试模式可以查看具体的执行流程。
  • hexo clean与删除文件夹
    虽然 hexo clean 的效果是删除 public 目录和 db.json 文件，但建议始终使用命令行执行，而不是手动删除文件夹。因为命令行操作是原子性的，且能确保缓存状态的一致性，避免因手动误删导致的意外问题。

配置示例

以下是一些常用指令的实战示例，涵盖了从初始化到日常维护的全流程。

初始化项目

1
2
3
4
5
6
7
8
# 在当前目录初始化 Hexo 项目
hexo init

# 在指定目录创建项目
hexo init my-blog

# 初始化后，进入项目目录安装依赖（通常 init 会自动执行）
cd my-blog && npm install

创建内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建一篇默认布局的文章，标题为 "Hello World"
hexo new "Hello World"

# 创建一篇名为 "About" 的页面（会生成 source/about/index.md）
hexo new page "About"

# 创建一篇草稿（会生成 source/_drafts/xxx.md）
hexo new draft "My Draft"

# 自定义文章路径（注意：标题必须放在最后）
hexo new post --path "categories/node-js/intro" "Node.js 入门"

# 如果标题包含空格，务必使用引号
hexo new "This is a Title with Spaces"

生成与预览

1
2
3
4
5
6
7
8
9
10
11
# 生成静态文件
hexo generate

# 监视文件变动并自动重新生成（配合本地服务器使用）
hexo generate --watch

# 简写形式（常用）
hexo g -w

# 强制重新生成所有文件
hexo generate --force

部署与清理

1
2
3
4
5
6
7
8
# 部署前强制重新生成文件
hexo deploy --generate

# 简写
hexo d -g

# 清理缓存和旧文件（常用组合）
hexo clean && hexo generate

调试与自定义配置

1
2
3
4
5
6
7
8
9
10
11
# 使用自定义配置文件启动服务器
hexo server --config custom.yml

# 同时使用多个配置文件（后面的覆盖前面的）
hexo server --config custom.yml,custom2.json

# 在安全模式下启动，不加载插件
hexo server --safe

# 显示调试信息
hexo --debug generate

注意事项

  • 标题规范：在使用 hexo new 命令时，如果标题包含空格，请务必使用引号将标题括起来，否则命令会解析失败或产生错误的文件名。
  • 依赖管理：hexo init 会自动尝试安装依赖。如果你的环境中安装了多个包管理器（npm、Yarn、pnpm），Hexo 会优先使用列在前面的。如果自动安装失败，建议手动进入项目目录执行 npm install。
  • 缓存机制：Hexo 会缓存路由信息以提高生成速度。当你手动修改了文件结构或路由配置后，如果发现页面没有更新，很可能是缓存导致的。此时执行 hexo clean 清除缓存即可。
  • 路径参数：在使用 --path 参数时，路径是相对于 source 目录的。例如，hexo new page --path about/me "About me" 会在 source 目录下创建 about/me.md 文件。
  • 配置文件合并：使用 --config 指定多个文件时，文件名之间不能有空格，且后面的文件中的值会覆盖前面的文件中的同名值。