add readme
This commit is contained in:
tianjincai
143
README.md
143
README.md
@@ -1,59 +1,116 @@
|
|||||||
# hexo-deployer-s3
|
---
|
||||||
|
|
||||||
Amazon S3 deployer plugin for [Hexo](http://hexo.io/)
|
# Hexo Deployer for S3-Compatible Services
|
||||||
|
|
||||||
|
[](https://www.npmjs.com/package/hexo-deployer-s3)
|
||||||
|
[](https://www.npmjs.com/package/hexo-deployer-s3)
|
||||||
|
|
||||||
|
This is a deployment plugin for [Hexo](https://hexo.io) 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**
|
||||||
|
* **Teby.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
|
## Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ npm install hexo-deployer-s3 --save
|
npm install hexo-deployer-s3 --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.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# _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
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# _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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hexo clean && hexo generate && hexo deploy
|
||||||
```
|
```
|
||||||
|
|
||||||
## Options
|
## Options
|
||||||
|
|
||||||
You can configure this plugin in `_config.yml`.
|
| 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. |
|
||||||
|
|
||||||
``` yaml
|
## Troubleshooting
|
||||||
# You can use this:
|
|
||||||
deploy:
|
|
||||||
type: s3
|
|
||||||
bucket: <S3 bucket>
|
|
||||||
aws_key: <AWS id key> // Optional, if the environment variable `AWS_ACCESS_KEY_ID` is set
|
|
||||||
aws_secret: <AWS secret key> // Optional, if the environment variable `AWS_SECRET_ACCESS_KEY` is set
|
|
||||||
aws_cli_profile: <an AWS CLI profile name, e.g. 'default'> // Optional
|
|
||||||
concurrency: <number of connections> // Optional
|
|
||||||
region: <region> // Optional, see https://github.com/LearnBoost/knox#region
|
|
||||||
headers: <headers in JSON format> // pass any headers to S3, usefull for metadata cache setting of Hexo assets
|
|
||||||
prefix: <prefix> // Optional, prefix ending in /
|
|
||||||
delete_removed: <true|false> // if true will delete removed files from S3. Default: true
|
|
||||||
endpoint: <endpoint> // Optional, for S3 compatiable services
|
|
||||||
```
|
|
||||||
|
|
||||||
If you installed the AWS command-line tool and provided your credentials via `aws configure`,
|
- **`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`).
|
||||||
you can re-use those credentials. Specify a value for `aws_cli_profile`, such as "default",
|
|
||||||
and leave `aws_key`, `aws_secret`, and `region` blank.
|
|
||||||
If you provide key, secret, and/or region explicitly or via the environment,
|
|
||||||
they will override what's in your AWS CLI profile.
|
|
||||||
|
|
||||||
#### Example: header Cache-Control
|
- **`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)
|
||||||
|
|
||||||
``` yaml
|
- **Connection Errors**: Double-check your `endpoint` URL for typos. Ensure there is no firewall blocking the connection to the endpoint.
|
||||||
deploy:
|
|
||||||
type: s3
|
|
||||||
bucket: my-site-bucket
|
|
||||||
headers: {CacheControl: 'max-age=604800, public'}
|
|
||||||
```
|
|
||||||
|
|
||||||
This will set "Cache-Control" header in every file deployed to max-age 1 week. This solves "Leverage browser caching" on most page speed analyzers. For custom metadata use:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
headers: {Metadata : { x-amz-meta-mykey: "my value" }}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Contributors
|
|
||||||
|
|
||||||
- Josh Strange ([joshstrange](https://github.com/joshstrange); original implementation)
|
|
||||||
- Josenivaldo Benito Jr. ([JrBenito](https://github.com/jrbenito))
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
[MIT](https://opensource.org/licenses/MIT)
|
||||||
2
index.js
2
index.js
@@ -1,3 +1 @@
|
|||||||
console.log('--- Hexo Deployer S3 plugin is being loaded! ---'); // <--- 添加这行
|
|
||||||
|
|
||||||
hexo.extend.deployer.register('s3', require('./lib/deployer'));
|
hexo.extend.deployer.register('s3', require('./lib/deployer'));
|
||||||
@@ -1,5 +1,3 @@
|
|||||||
// deployer.js
|
|
||||||
|
|
||||||
const { S3Client, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
|
const { S3Client, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
|
||||||
const { Upload } = require('@aws-sdk/lib-storage');
|
const { Upload } = require('@aws-sdk/lib-storage');
|
||||||
const fs = require('fs');
|
const fs = require('fs');
|
||||||
@@ -151,7 +149,7 @@ module.exports = async function(args) {
|
|||||||
|
|
||||||
try {
|
try {
|
||||||
await Promise.all(uploadPromises);
|
await Promise.all(uploadPromises);
|
||||||
log.info('All files uploaded successfully!');
|
log.info(chalk.green('All files uploaded successfully!'));
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
log.error('An error occurred during upload:');
|
log.error('An error occurred during upload:');
|
||||||
log.error(err);
|
log.error(err);
|
||||||
|
|||||||
Reference in New Issue
Block a user