hexo-deployer-s3-plus/README_zh.md at ca046ef16039996084e185f62bdb2a9a2926534a

YunxiaoXu/hexo-deployer-s3-plus

Fork 0

Files

Yunxiao Xu ca046ef160 Update Readme

2025-09-11 17:37:16 -07:00

7.7 KiB

Raw Blame History

这是一款为 Hexo 设计的部署插件，它允许您将静态网站部署到任何与 S3 兼容的对象存储服务。它基于 AWS SDK v3 构建，确保了现代化的功能和强大的性能。

这款插件完美适用于：

AWS S3
Teby.io
MinIO
Cloudflare R2
DigitalOcean Spaces
以及任何其他提供 S3 兼容 API 的存储服务。

功能特性

广泛的兼容性: 只需提供一个端点（endpoint），即可部署到任何兼容 S3 的服务。
并发上传: 利用 p-limit 并行上传多个文件，显著提升部署速度。
同步删除: 自动检测并删除存储桶中那些在本地构建目录已不存在的文件 (delete_removed)。
自定义头信息: 为您的文件设置自定义 HTTP 头（例如 Cache-Control）。
支持子目录: 将您的网站部署到存储桶内的指定前缀（子目录）下。
灵活的凭证处理: 可从 _config.yml、环境变量或 AWS CLI 配置文件中读取凭证。

安装

npm install hexo-deployer-s3-plus --save

配置

将以下配置添加到您的 _config.yml 文件中。

通用 S3 服务配置示例 (如 Teby.io, MinIO, R2)

对于任何非 AWS 的 S3 服务，推荐使用此配置。

# _config.yml
deploy:
  type: s3
  bucket: your-bucket-name                       # 你的存储桶名称
  endpoint: https://s3.your-service-provider.com  # 你的服务商提供的 S3 端点
  access_key_id: YOUR_ACCESS_KEY                  # 你的 Access Key
  secret_access_key: YOUR_SECRET_KEY              # 你的 Secret Key
  region: us-east-1 # SDK 通常需要这个字段，但对于非 AWS 服务，它可以是任意字符串
  
  # 可选设置:
  concurrency: 20      # 并发上传数量
  delete_removed: true # 是否删除云端多余文件
  prefix: blog/        # 上传到存储桶的子目录

AWS S3 配置示例

# _config.yml
deploy:
  type: s3
  bucket: your-aws-s3-bucket-name # 你的 AWS S3 存储桶名称
  region: your-aws-region         # 你的 AWS 区域, e.g., us-west-2
  endpoint: https://s3.your-aws-region.amazonaws.com # 对应区域的 AWS S3 端点
  
  # 如果凭证已设置为环境变量 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) 
  # 或通过 AWS profile 配置，则此处可以省略
  # access_key_id: YOUR_AWS_ACCESS_KEY_ID
  # secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
  
  # 可选设置:
  aws_cli_profile: my-work-profile # 使用 ~/.aws/credentials 文件中的特定 profile
  concurrency: 20
  delete_removed: true

使用方法

配置完成后，您可以通过以下命令来部署您的网站：

hexo clean && hexo generate && hexo deploy

配置选项

参数	必需 / 可选	描述
`bucket`	必需	您的 S3 存储桶的名称。
`endpoint`	必需	您的存储服务商提供的 S3 API 端点 URL。对于 AWS，它类似于 `https://s3.us-east-1.amazonaws.com`。
`access_key_id`	可选	您的访问密钥。也可以通过 `aws_key` 设置。如果使用环境变量或 AWS profile，则可省略。
`secret_access_key`	可选	您的私有密钥。也可以通过 `aws_secret` 设置。如果使用环境变量或 AWS profile，则可省略。
`region`	可选	您的存储桶所在的区域。对于 AWS S3 至关重要。对于其他 S3 服务，这通常可以是一个占位符字符串（如 `us-east-1`），但仍建议填写。
`prefix`	可选	文件将被上传到的存储桶内的子目录。例如：`blog/`。
`concurrency`	可选	并行上传的文件数量。默认为 `20`。
`delete_removed`	可选	如果为 `true`，部署时将自动删除存储桶中存在但本地 `public` 文件夹中不存在的文件。默认为 `true`。设置为 `false` 可禁用此同步功能。
`force_path_style`	可选	如果为`true`，S3 API 端点 URL 会使用 Path Style 而非 Virtual Host Style。默认为 `true`。设置为 `false` 可禁用此功能。
`headers`	可选	应用于所有已上传文件的 HTTP 头的 JSON 对象。可用于设置缓存策略。示例：`headers: {"Cache-Control": "max-age=31536000"}`。
`aws_cli_profile`	可选	您 `~/.aws/credentials` 文件中用于身份验证的 profile 名称。如果直接提供了 `access_key_id` 和 `secret_access_key`，则此项将被忽略。
`aws_key`, `aws_secret`	可选	`access_key_id` 和 `secret_access_key` 的旧别名，用于向后兼容。

问题排查

TypeError: ... is not a function: 此类错误通常由 chalk 或 p-limit 等依赖的模块系统冲突 (CommonJS vs. ES Modules) 引起。请确保您以正确的方式引入它们，例如：const pLimit = require('p-limit').default;。如果问题依旧存在，请尝试安装一个特定的兼容版本（例如 npm install chalk@4）。
Access Denied / 403 Forbidden (访问被拒绝): 这几乎总是权限问题。请检查您使用的 API 密钥 (Access Key) 是否在存储桶上具有所需的权限：
- s3:PutObject (用于上传)
- s3:ListBucket (用于检查待删除文件)
- s3:DeleteObject (用于删除文件)
- s3:GetObject (如果涉及读取操作，尽管部署时非必需)
Connection Errors (连接错误): 仔细检查您的 endpoint URL 是否有拼写错误。确保没有防火墙阻止与该端点的连接。

许可证

MIT

7.7 KiB Raw Blame History Unescape Escape