hexo 学习►写作

hexo 学习 0021:hexo 资源文件夹

管理博客中的图片、CSS 或 JS 文件时，如果所有资源都堆在一个大文件夹里，随着文章增多，你会很难分清哪张图片属于哪篇文章。Hexo 提供的“资源文件夹（Asset Folder）”功能，就像是为每篇文章配备了一个专属的“附件箱”，让资源管理与文章本身紧密绑定。

全局资源文件夹 vs 文章资源文件夹

在深入配置之前，我们需要区分两种资源管理方式：

1. 全局资源文件夹
这是最基础的方式。你可以将所有公共图片放在 source/images 这样的目录下。

  • 引用方式：使用绝对路径，例如 ![](/images/image.jpg)。
  • 适用场景：适用于全站通用的资源，如 Logo、背景图、公共图标等。
  • 缺点：当项目变大，这个文件夹会变得杂乱无章，难以维护特定文章独有的素材。

2. 文章资源文件夹 (Post Asset Folder)
这是更高级的组织方式。它为每一篇文章创建一个同名的文件夹，专门存放该文章独有的资源。

  • 核心优势：资源与文章一一对应，删除文章时资源也能一并清理，且支持相对路径引用，迁移文章时更方便。
  • 比喻：如果把文章比作“信件”，全局文件夹像是“公共仓库”，而文章资源文件夹则是随信附带的“专用信封”，里面只装这封信需要的照片和附件。

配置说明与开启方法

要启用文章资源文件夹功能，你需要修改站点根目录下的 _config.yml 配置文件。

配置项： post_asset_folder

  • 作用：控制是否在为每篇新文章创建时，自动生成一个同名的资源文件夹。
  • 默认值：false (关闭)
  • 开启设置：
1
post_asset_folder: true

工作流程变化：
开启此选项后，当你执行新建文章命令时：

1
hexo new post "my-first-trip"

Hexo 不仅会创建 source/_posts/my-first-trip.md，还会自动创建一个名为 source/_posts/my-first-trip/ 的文件夹。你只需要将与这篇文章相关的图片（如 photo1.jpg）放入这个文件夹中即可。

引用资源的正确姿势

开启资源文件夹后，引用方式发生了关键变化。如果你继续使用标准的 Markdown 语法（如 ![](photo1.jpg)），图片在首页或归档页可能会无法显示。这是因为 Hexo 需要特殊的处理逻辑来解析相对路径。

方法一：使用标签插件 (推荐，兼容性最好)

Hexo 提供了三个专用的标签插件来引用文章资源文件夹中的内容。这些插件能确保图片在文章页、首页和归档页都能正确渲染。

1. 引用图片 (asset_img)

  • 语法：{% asset_img slug [title] %}
  • 参数说明：
    • slug：文件名（包含扩展名）。如果文件名包含空格，需用引号包裹。
    • title：可选，图片的标题或 alt 文本。

示例：

1
2
3
4
5
<!-- 基本用法 -->
{% asset_img example.jpg This is an example image %}

<!-- 文件名带空格的情况 -->
{% asset_img "my vacation photo.jpg" "Spaced title example" %}

2. 引用资源路径 (asset_path)

  • 语法：{% asset_path slug %}
  • 作用：仅获取资源的相对路径链接，不直接渲染图片或标签。常用于自定义 HTML 结构或脚本引用。

示例：

1
{% asset_path script.js %}

3. 引用资源链接 (asset_link)

  • 语法：{% asset_link slug [title] %}
  • 作用：生成一个指向资源文件的下载链接或访问链接。

示例：

1
{% asset_link "data-sheet.pdf" "下载数据表" %}

概念辨析：为什么不能用 ![](image.jpg)？
在标准 Markdown 中，![](image.jpg) 是相对于当前 Markdown 文件所在路径的。但在 Hexo 生成静态网站时，文章会被渲染到不同的目录层级（如 /2026/03/09/title/index.html）。如果不经过特殊处理，简单的相对路径在首页（通常是列表页）会找不到图片资源。标签插件 asset_img 会自动计算正确的绝对路径，确保在任何页面都能显示。

方法二：在 Markdown 中直接嵌入 (需特定配置)

如果你更喜欢原生 Markdown 语法，不想写 {% %} 标签，可以通过配置 hexo-renderer-marked 插件来实现自动解析。

前提条件：

  1. 已开启 post_asset_folder: true。
  2. 安装了 hexo-renderer-marked 3.1.0 或更高版本。

配置步骤：
在 _config.yml 中添加或修改 marked 配置块：

1
2
3
4
5
post_asset_folder: true

marked:
  prependRoot: true
  postAsset: true

参数说明：

  • prependRoot: 在路径前添加根路径。
  • postAsset: 启用文章资源自动解析功能。

效果示例：
配置完成后，你可以直接在文章中使用标准 Markdown 语法：

1
![描述文字](image.jpg)

Hexo 会自动将其解析为正确的路径。例如，如果文章位于 /2020/01/02/foo/，图片 image.jpg 在该文章的资源文件夹中，上述语法会被渲染为：

1
<img src="/2020/01/02/foo/image.jpg" alt="描述文字">

总结与建议

  • 少量公共资源：继续使用 source/images 配合 ![](/images/...)。
  • 文章独有资源：务必开启 post_asset_folder: true。
  • 引用方式选择：
    • 如果你需要最大的兼容性和对旧主题的支持，请使用 {% asset_img ... %} 标签插件。
    • 如果你追求写作流畅度，且使用的是较新的 hexo-renderer-marked 和现代主题，可以配置 marked.postAsset: true 从而直接使用 ![](...) 语法。
  • 注意事项：一旦开启资源文件夹功能，请养成将图片放入对应文章文件夹的习惯，避免文件散落在 source/_posts 根目录下造成混乱。