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