hexo-deployer-tencent

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

功能概述

该插件提供以下功能：

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

安装使用

1. 在 Hexo 项目根目录下运行以下命令安装插件：

   npm install hexo-deployer-tencent

2. 运行以下命令生成并部署静态文件：

   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 | 否 | 无 | 忽略路径[^1]，支持多个相对（upload_dir）路径。 | | cdn_domains.ignore_extensions | Array | 否 | 无 | 忽略格式[^2]，例：['.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 刷新[^3]，其它按照 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

[^1]: 对于指定路径（如 /fonts）下的请求地址，即使目录中的文件发生变更，也不会触发缓存刷新。

[^2]: 对于特定文件格式（如 *.css），请求地址将不触发缓存刷新，即使文件内容已发生变更。

[^3]: 当待刷新链接未超过配额时，优先按 URL 进行刷新（清除缓存）；一旦超出配额，则按 Hostname 执行刷新（标记过期）。