---

Hexo Deployer for S3-Compatible Services

English|简体中文

This is a deployment plugin for Hexo that allows you to deploy your static site to any S3-compatible object storage service. It is built using the AWS SDK v3, ensuring modern features and robust performance.

This plugin is perfect for:

• AWS S3
• Tebi.io
• MinIO
• Cloudflare R2
• DigitalOcean Spaces
• And any other storage provider that exposes an S3-compatible API.

Features

• Broad Compatibility: Deploy to any S3-compatible service by simply providing an endpoint.
• Concurrent Uploads: Utilizes p-limit to upload multiple files in parallel, significantly speeding up deployment.
• Sync with Deletion: Automatically detects and deletes files from the bucket that are no longer present in your local build (delete_removed).
• Custom Headers: Set custom HTTP headers (e.g., Cache-Control) for your files.
• Sub-directory Support: Deploy your site into a specific prefix (sub-directory) within your bucket.
• Flexible Credential Handling: Reads credentials from your _config.yml, environment variables, or AWS CLI profiles.

Installation

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

Configuration

Add the following configuration to your _config.yml file.

Example for a Generic S3 Service (like Teby.io, MinIO, R2)

This is the recommended configuration for any non-AWS S3 service.

# _config.yml
deploy:
  type: s3
  bucket: your-bucket-name
  endpoint: https://s3.your-service-provider.com
  access_key_id: YOUR_ACCESS_KEY
  secret_access_key: YOUR_SECRET_KEY
  region: us-east-1 # This is often required by the SDK, but can be any string for non-AWS services.
  
  # Optional settings:
  concurrency: 20
  delete_removed: true
  prefix: blog/

Example for AWS S3

# _config.yml
deploy:
  type: s3
  bucket: your-aws-s3-bucket-name
  region: your-aws-region # e.g., us-west-2
  endpoint: https://s3.your-aws-region.amazonaws.com # The AWS S3 endpoint for your region
  
  # Credentials can be omitted if they are set as environment variables 
  # (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or via an AWS profile.
  # access_key_id: YOUR_AWS_ACCESS_KEY_ID
  # secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
  
  # Optional settings:
  aws_cli_profile: my-work-profile # Use a specific profile from ~/.aws/credentials
  concurrency: 20
  delete_removed: true

Usage

After configuring, you can deploy your site with the following command:

hexo clean && hexo generate && hexo deploy

Options

Parameter	Required / Optional	Description
bucket	Required	The name of your S3 bucket.
endpoint	Required	The S3 API endpoint URL of your storage provider. For AWS, this would be like https://s3.us-east-1.amazonaws.com.
access_key_id	Optional	Your access key. Can also be set via aws_key. Omit if using environment variables or an AWS profile.
secret_access_key	Optional	Your secret key. Can also be set via aws_secret. Omit if using environment variables or an AWS profile.
region	Optional	The region of your bucket. Crucial for AWS S3. For other S3 services, this can often be a placeholder string like us-east-1, but is still recommended.
prefix	Optional	A sub-directory inside your bucket where the files will be uploaded. E.g., blog/.
concurrency	Optional	The number of files to upload in parallel. Defaults to 20.
delete_removed	Optional	If true, files in the bucket that don't exist in your local public folder will be deleted upon deployment. Defaults to true. Set to false to disable this synchronization.
headers	Optional	A JSON object of HTTP headers to apply to all uploaded files. Useful for setting caching policies. Example: headers: {"Cache-Control": "max-age=31536000"}.
aws_cli_profile	Optional	The name of a profile in your ~/.aws/credentials file to use for authentication. Ignored if access_key_id and secret_access_key are provided directly.
aws_key, aws_secret	Optional	Legacy aliases for access_key_id and secret_access_key for backward compatibility.

Troubleshooting

• TypeError: ... is not a function: This often happens with dependencies like chalk or p-limit due to module system conflicts (CommonJS vs. ES Modules). Ensure you are requiring them correctly, for example: const pLimit = require('p-limit').default;. If the problem persists, try installing a specific compatible version (e.g., npm install chalk@4).

• Access Denied / 403 Forbidden: This is almost always a permissions issue. Check that the API key (Access Key) you are using has the required permissions on the bucket:

  • s3:PutObject (for uploading)
  • s3:ListBucket (for checking files to delete)
  • s3:DeleteObject (for deleting removed files)
  • s3:GetObject (if you have any read operations, though not required for deploy)

• Connection Errors: Double-check your endpoint URL for typos. Ensure there is no firewall blocking the connection to the endpoint.

License

MIT