Hexo 部署插件：腾讯云 OSS

一个 Hexo 部署插件，用于将静态文件上传到腾讯云对象存储（COS）并刷新 CDN/EdgeOne 缓存。

更新：现在支持将 EdgeOne 作为缓存刷新对象。处理逻辑如下：通过查询域名的缓存清除配额，识别当前为免费版或付费版。如果单次刷新地址数量超过免费版配额，将按hostname维度执行标记过期；其他情况下则按具体URL地址进行清除缓存。

一、背景

事实上，我此前在部署到腾讯云对象存储时使用的插件是 lxl80/hexo-deployer-cos-cdn。

然而，在使用这个插件时遇到了两个问题：① 该项目使用的是云 API 2.0，而腾讯云计划在2025年4月30日正式下线2.0版本，全面升级到 API 3.0。②博客的永久链接中去掉了 index.html，在刷新缓存时，插件以文件路径作为访问地址进行缓存刷新，而非实际永久链接地址。

后者还好，前者就迫在眉睫、急需解决了。因此，我决定造个新轮子，尝试解决这两个问题。由于目前使用的是腾讯云，所以放弃了阿里云部分，并根据个人使用习惯改进了缓存刷新逻辑：

由于我不太信任第三方图床服务，博客中的所有图片资源和其他静态文件都是一起打包上传到对象存储中的，而不是分离上传到不同的 bucket。此外，我希望对静态资源的引用加上防盗链配置。然而，如果对博客的主域名设置防盗链，会导致外链跳转访问时请求失败，因为携带了白名单之外的 referer。所以，我采用了一个 bucket 绑定多个自定义域名的方案，通过在 CDN 中对资源回源请求添加限制^[1]，确保主域名不返回静态资源，而由启用防盗链的域名返回静态资源^[2]。

总结：cdn_domains 支持多域名配置。而为了减少刷新缓存时的无效链接（例如刷新主域名的静态资源地址），添加了ignore_extensions和ignore_paths选项，可以灵活的选择过滤目录和文件格式。

以上。

二、项目

项目地址

hexo-deployer-tencent

https://github.com

说明文档

功能概述

该插件提供以下功能：

将指定路径的静态文件上传至腾讯云对象存储，通过 MD5 校验仅上传变更内容。
支持根据配置自动清理对象存储（COS）中的冗余文件，默认关闭此功能。
依据配置，使用指定域名刷新变更文件的（CDN/EdgeOne）缓存，支持配置多个域名。
可根据配置文件，在刷新缓存时过滤指定目录下的文件，灵活控制刷新范围。
可根据配置文件，在刷新缓存时将永久链接尾部的 index.html 转换为根路径形式。

安装使用

在 Hexo 项目根目录下运行以下命令安装插件：
npm install hexo-deployer-tencent
运行以下命令生成并部署静态文件：
hexo generate && hexo deploy

配置示例

在 Hexo 的 _config.yml 中添加以下配置：

deploy:
  type: tencent-cos
  secret_id: your_secret_id
  secret_key: your_secret_key
  bucket: your_bucket
  region: your_region
  upload_dir: public  # 默认上传 Hexo 的 public 目录
  cache_type: cdn # 可选值 cdn（默认）, edgeone
  cdn_domains:
      - domain: https://static.example.com
        ignore_extensions: ['.html']
      - domain: https://example.com
        ignore_paths: ['/js', '/css', '/img']
  remove_remote_files: true  # 是否删除 COS 中多余的远程文件
  refresh_index_page: true  # 是否将 index.html 刷新为根路径
  concurrency: 10  # 腾讯云 API 并发数

cdn_domains 支持配置多个域名，适用于一个存储桶绑定多个自定义域名的场景，可通过 ignore_paths 和 ignore_extensions 灵活指定刷新时需要过滤的目录或文件格式。

属性说明

属性名	类型	是否必填	默认值	描述
`secret_id`	String	是	无	腾讯云 API 的 Secret ID，用于身份验证。
`secret_key`	String	是	无	腾讯云 API 的 Secret Key，用于身份验证。
`bucket`	String	是	无	腾讯云 COS 的存储桶名称，例如 `my-bucket-1250000000`。
`region`	String	是	无	存储桶所在区域，例如 `ap-guangzhou`。
`upload_dir`	String	是	无	本地上传目录，相对于 Hexo 根目录，通常为 `public`。
`cache_type`	String	否	`cdn`	刷新类型，支持 `cdn`（默认值）和 `edgeone`。
`cdn_domains`	Array	否	`[]`	加速域名列表，每项可包含 `ignore_paths`，未设置则不刷新缓存。
`cdn_domains.domain`	String	是	无	加速域名，以 `https://` 或 `http://` 开头。
`cdn_domains.ignore_paths`	Array	否	无	忽略路径^[3]，支持多个相对（`upload_dir`）路径。
`cdn_domains.ignore_extensions`	Array	否	无	忽略格式^[4]，例：[‘.html’, ‘.txt’]。
`remove_remote_files`	Boolean	否	`false`	是否删除 COS 中不在本地文件列表中的远程文件。
`refresh_index_page`	Boolean	否	`false`	是否将 `index.html` 的刷新 URL 转换为根路径（例如 `/`）。
`concurrency`	Number	否	`10`	文件上传和缓存刷新的并发数，受限于腾讯云 API 并发限制。

注意事项

必填项：secret_id、secret_key、bucket、region 和 upload_dir 是必须提供的。
可选项：未设置的可选项将使用默认值，默认行为是上传文件但不删除远程文件或刷新缓存。
刷新类型：cdn 按照 url 刷新；edgeone 免费版按照 hostname 刷新^[5]，其它按照 url 刷新。
路径处理：upload_dir 是相对于 Hexo 项目根目录的路径，通常应设置为 public。
永久链接：当永久链接中去除尾部的 index.html 时，刷新缓存时应刷新 / 而非 /index.html。

工作流程

Hexo 部署插件注册
- hexo.extend.deployer.register：注册 Hexo 部署插件。
Hexo 部署插件
- 部署入口：处理部署主逻辑。
- 主要入口：main - 协调部署任务，同步和刷新。
- changedFiles - 记录变更文件，记录变更文件并进行部署。
部署入口
- 缓存管理：管理节点缓存。
  - purgeCdnCache - 刷新 CDN 缓存。
  - purgeEdgeoneCache - 刷新 EdgeOne 缓存。
- 核心流程：执行核心部署流程。
  - 核心流程：处理核心部署逻辑。
    - 配置管理：管理配置。
      - validateConfig - 校验部署配置，校验并部署配置。
    - 初始化客户端：初始化 COS 和 CDN 客户端。
      - initClients - 初始化 COS 和 CDN 实例。
    - 计算 MD5：计算文件 MD5。
      - calculateMD5 - 计算文件哈希值。
    - 获取文件：获取文件列表。
      - getFiles - 递归获取本地文件。
      - listCosFiles - 获取 COS 文件列表。
    - 上传文件：上传文件到 COS。
      - uploadFile - 上传文件到 COS。
    - 删除 COS 文件：删除 COS 文件。
      - deleteCosFiles - 删除多余或不再需要的文件。

许可证

MIT License

可在回源配置中，使用回源URL重写配置，指定路径重定向资源，限制返回内容。 ↩︎
静态资源引用优化：可参考 ①Gulp-替换静态资源链接，②静态网站图片优化。 ↩︎
对于指定路径（如 /fonts）下的请求地址，即使目录中的文件发生变更，也不会触发缓存刷新。 ↩︎
对于特定文件格式（如 *.css），请求地址将不触发缓存刷新，即使文件内容已发生变更。 ↩︎
当待刷新链接未超过配额时，优先按 URL 进行刷新（清除缓存）；一旦超出配额，则按 Hostname 执行刷新（标记过期）。 ↩︎