add chinese manual
This commit is contained in:
tianjincai
112
README_zh.md
Normal file
112
README_zh.md
Normal file
@@ -0,0 +1,112 @@
|
||||
[](https://www.npmjs.com/package/hexo-deployer-s3-plus)
|
||||
[](https://www.npmjs.com/package/hexo-deployer-s3-plus)
|
||||
|
||||
这是一款为 [Hexo](https://hexo.io) 设计的部署插件，它允许您将静态网站部署到任何与 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 配置文件中读取凭证。
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
npm install hexo-deployer-s3-plus --save
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
将以下配置添加到您的 `_config.yml` 文件中。
|
||||
|
||||
### 通用 S3 服务配置示例 (如 Teby.io, MinIO, R2)
|
||||
|
||||
对于任何非 AWS 的 S3 服务，推荐使用此配置。
|
||||
|
||||
```yaml
|
||||
# _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 配置示例
|
||||
|
||||
```yaml
|
||||
# _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
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
配置完成后，您可以通过以下命令来部署您的网站：
|
||||
|
||||
```bash
|
||||
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` 可禁用此同步功能。 |
|
||||
| `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](https://opensource.org/licenses/MIT)
|
||||
Reference in New Issue
Block a user