hexo 学习►配置

hexo 学习 0014:hexo 包含/不包含配置

在 Hexo 博客的配置中，include、exclude 和 ignore 这三个选项用于精确控制哪些文件或目录参与生成过程。虽然它们都涉及“包含”或“排除”的概念，但其作用范围和优先级有严格的区别。本文将详细解析这三个配置项的用法、差异及注意事项。

核心配置项说明

include、exclude 和 ignore 都使用 glob 表达式进行路径匹配，但它们的作用对象和层级不同。

  • include
    该选项用于明确指定需要处理的文件或目录，特别是那些通常被忽略的“隐藏文件”。在 Hexo 中，名称以下划线 _ 开头的文件或文件夹默认被视为隐藏文件，不会被处理。通过在 include 列表中声明这些文件的路径，可以强制 Hexo 处理它们。注意：此选项仅作用于 source/ 目录。
  • exclude
    该选项用于排除（不处理）指定的文件或目录。它同样只作用于 source/ 目录。你可以使用它来阻止某些特定的资源文件（如测试文件）被复制到生成的静态网站中。
  • ignore
    该选项用于忽略文件或文件夹，其作用范围比 exclude 更广。ignore 会应用到所有文件夹，包括 source/、themes/ 等。这是在项目中忽略某些主题文件或特定目录的通用方法。

概念辨析：作用范围与优先级

这三个配置项最核心的区别在于它们的作用范围和处理优先级：

  • 作用范围差异：
    include 和 exclude 是“源文件”级别的配置，它们只对 source/ 目录下的内容有效。而 ignore 是全局级别的配置，对项目根目录下的所有文件夹都有效。例如，如果你想忽略某个主题（theme）中的文件，必须使用 ignore，因为 exclude 对 themes/ 目录无效。
  • 特殊目录 _posts 的处理：
    source/_posts 目录是一个例外情况。不建议在此目录中使用 include 规则。如果需要忽略 _posts 目录下的文件，推荐的做法是在文件名前添加下划线 _（使其成为隐藏文件），或者使用 skip_render 插件功能，而不是使用 exclude。
  • 优先级关系：
    虽然配置中未明确说明三者之间的绝对优先级，但从逻辑上推断，ignore 作为全局忽略指令，其作用层级最高；include 和 exclude 作为源目录的包含/排除指令，作用层级次之，且两者互斥。通常，ignore 会无条件忽略文件，而 include 可以用来“抢救”被默认规则隐藏的文件。

配置示例

以下是一个综合的配置示例，展示了如何使用 glob 表达式来精确控制文件处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 包含或不包含配置
include:
  # 处理隐藏的 .nojekyll 文件（通常用于 GitHub Pages）
  - ".nojekyll"
  # 处理 source/css/ 目录下名为 _typing.css 的文件
  - "css/_typing.css"
  # 处理 source/_css/ 目录下的任何文件（不包括子目录中的文件）
  - "_css/*"
  # 处理 source/_css/ 目录下的任何文件，包括所有子目录中的文件
  - "_css/**/*"

exclude:
  # 不处理 source/js/test.js 文件
  - "js/test.js"
  # 不处理 source/js/ 目录下的文件，但包括子目录（此规则实际效果可能受限于具体版本，通常用于匹配一级文件）
  - "js/*"
  # 不处理 source/js/ 目录下的所有文件和子目录中的任何文件
  - "js/**/*"
  # 不处理 source/js/ 目录下文件名以 'test' 开头的文件
  - "js/test*"

ignore:
  # 忽略项目中任何一个名叫 'foo' 的文件夹（全局搜索）
  - "**/foo"
  # 只忽略 themes/ 目录下的直接子目录中名叫 'foo' 的文件夹
  - "**/themes/*/foo"
  # 忽略 themes/ 目录下每个文件夹中（包括深层嵌套）名叫 'foo' 的子文件夹
  - "**/themes/**/foo"

注意事项

  • 引号包裹：配置列表中的每一项路径都必须用单引号 ' ' 或双引号 " " 包裹起来，这是 YAML 语法的要求，也是为了防止特殊字符（如 *）被错误解析。
  • _posts 目录：再次强调，不要尝试使用 exclude 来忽略 source/_posts/ 目录中的文件，这通常无效。请使用文件名前缀 _ 或 skip_render 功能。
  • themes 目录：由于 exclude 对 themes/ 目录无效，如果需要在主题中忽略某些文件，请务必使用 ignore 配置。
  • glob 语法：** 用于匹配零级或多级目录，* 用于匹配单级目录或文件。理解这些通配符的含义对于编写正确的匹配规则至关重要。